Feature/skill self debug and systemd service

[keithy]

📝 Description
This PR introduces essential stability and observability features for PicoClaw.
It adds a Self-Debug Skill to allow the agent to diagnose its own execution failures from logs
and a Systemd Service installer to ensure the agent runs as a persistent, background daemon.

🗣️ Type of Change
[ ] 🐞 Bug fix (non-breaking change which fixes an issue)
[x] ✨ New feature (non-breaking change which adds functionality)
[ ] 📖 Documentation update
[x] ⚡ Code refactoring (improved service management)

🤖 AI Code Generation
[x] 👨‍💻 Mostly Human-written (Human lead)

🔗 Related Issue

• daemon feature #483
• feat(gateway): add daemon controls for background operation #810

📚 Technical Context
Reference URL: https://github.com/keithy/picoclaw/tree/feature/skill_self-debug_and_systemd_service

🧪 Test Environment
Hardware: Rock64 (ARM64)
OS: Debian/Ubuntu (Linux) armbian, mise
Channels: CLI / Local Daemon

☑️ Checklist
[x] My code/docs follow the style of this project.
[x] I have performed a self-review of my own changes.
[x] I have updated the documentation (added systemd instructions).

[keithy]

Note this is supplied as a self-contained skill, so that other options can be included easily.

[keithy]

Advanced use-cases

Although picoclaw has built in support for multiple agents, this scheme provides the flexibility for
parallel deployments with entirely different configurations e.g.

• Fixer - a second stable instance whose role is to be available to debug/monitor/fix the first.
• Blue/Green Stable/Canary pairings.
• Picoclaw farm

Personal note:
I use the fixer pattern, with the systemd.service unit installed, the default behaviour is to start and stop the service when the user logs in/out. The fixer runs under a separate user account and has sudo access to fix anything, so is under close supervison. This gives the ai a unique, in-situ position to debug and operate at a system level. For example, it helped me to compile and deploy the zfs kernel module into the rock64 on armbian.

[nikolasdehor]

Interesting and useful skill concept — self-debugging is a powerful capability. Several issues: (1) Shell injection risk: SKILL.md tools pass PICOCLAW_SERVICE_NAME directly into exec commands. If the service name contains shell metacharacters, this could be exploited. Consider validating/sanitizing the service name. (2) macOS script parity: The launchd script lacks error handling compared to systemd — uses 'which' instead of 'command -v', no check for picoclaw binary existence, missing trailing newline. (3) Log location on macOS: /tmp/service_name.log is world-readable and cleared on reboot. Consider ~/Library/Logs/. (4) SKILL.md quoting: exec picoclaw --config PICOCLAW_CONFIG status has nested double quotes that would break in shell. (5) Scope question: Is workspace/skills/ the correct location for bundled skills?

[keithy]

I am tidying this PR, watch this space.

[keithy]

Are you now explicitly blocking systemctl and journalctl ? The whole reason I am using picoclaw is to manage my infrastructure.

[keithy]

This PR has been reworked, all actions are implemented through a script with full parameter sanitization.
MacOS logs in ~/Library/Logs as suggested.

depends on: #896

[xiaket]

I'm tentative to close this PR. I know this may upset you, but please allow me to explain.

picoclaw is new, and it would be a heavy burden to maintain a long bash script, we don't even have CI to do spellcheck etc. I can see this has been packaged as a skill. I think it makes better sense to showcase this somehow, but it should not be part of the official skill. Because if we have, and if we have any issue in the script, the team would need to maintain it.

[keithy]

Hello, I purposefully packaged this as a skill, so that conversations like this can take place. This functionality belongs as a plug-in, and should not be part of the lean-thoroughbred binary. It is perfectly reasonable to avoid taking on additional responsibilities and encourage spawning of a second tier of community supported and maintained plugins.

However, the reason that I created this in the first place was to 'deamonstrate' that adding deamon support to the service would be un-necessary and unhelpful bloat, contrary to the unix philosophy of small tools, working in combination. The dependency direction ought to be one-way. A service should not need to know how it is run, and it may be run in different contexts.

The danger being that if you do not include this, and include something else, the two solutions will compete each other out. picoclaw-launcher is already in danger of doing just this. Perhaps, this also ought to be a separate project.

The long bash script is certainly overkill for your needs, it provides a lot more than the minimum. I propose that you help by doing the following:

a) support the basic mechanism (through env-vars/discoverability/plugin architecture etc.)
b) include and use minimal examples where it makes sense.
c) facilitate the plugin-ability of more grandiose pretentions.

Suggested path:

1. Please include feat(config): Add support for env var configuration #896 to support the basic mechanism
   1b) perhaps some additional non-breaking config items to support discoverability (e.g. config.json - daemon.start.exec)
2. consider bundling and supporting the minimal output of this skill, the basic systemd service on its own.
   2b) the installer can be provided as a make task (again this is orthogonal to the binary itself)
3. Have picoclaw-launcher use a level of discoverability. plugin-ness that comtributes, rather than competes.

Dont close it just yet. Use this an opportunity to come to some conclusions with respect to the above.

[xiaket]

thanks @keithy !

The danger being that if you do not include this, and include something else, the two solutions will compete each other out. picoclaw-launcher is already in danger of doing just this. Perhaps, this also ought to be a separate project.

I understand where you come from and I'm with you on this, in fact, there has been chats to have this launcher as a separate repo. And we cannot rule out the possibility that this launcher cmd got moved out one day.

Suggested path:

1. Please include feat(config): Add support for env var configuration #896 to support the basic mechanism

I think this has been merged in.

1b) perhaps some additional non-breaking config items to support discoverability (e.g. config.json - daemon.start.exec)

I'm not too sure about what this is. Do you mind explain a bit?

2. consider bundling and supporting the minimal output of this skill, the basic systemd service on its own.

If I can make the decision myself, I would probably leave this for the different distros to figure out. systemd/init/runit have their different way to daemonize a process. I myself do not want to get into the business of bundling OS specific mechanisms into a software. Like what you have said, we need to do one thing well ;)

3. Have picoclaw-launcher use a level of discoverability. plugin-ness that comtributes, rather than competes.

This makes sense, but I feel this PR should not be the right place for it.

WDYT?

[keithy]

  1b) perhaps some additional non-breaking config items to support discoverability (e.g. config.json - daemon.start.exec)
  
  > I'm not too sure about what this is. Do you mind explain a bit?

Allow for a relaxed schema (i.e. non-breaking) which allows for the possibility that plugins/addons managing part of the config.json to hold their own settings. Then the picoclaw-launcher-tui can have its own start/stop agent exec command hooks.

[keithy]

Now hosted here until a better home is found. https://github.com/keithy/angelhub.git

[xiaket]

Close per discussion, please feel free to re-open.

Thanks for your contribution, good discussion here!

[keithy]

#1130 adds plugins support so the install-service-systemd can install a picoclaw-service plugin