feat(update): /agent:update skill + heartbeat version-check

[JD2005L]

Summary

Companion to #9 — which disables Claude Code's in-process auto-updater for service-mode installs. Without an explicit update path, daemonized agents silently fall behind. This PR closes that loop with a detect-and-notify flow that doesn't introduce the very class of mid-run mutation #9 set out to prevent.

Two pieces:

1. New /agent:update skill (skills/update/SKILL.md)

User-invocable. Triggers on /agent:update, /update, "check for updates", "are there updates", "buscar actualizaciones".

What it does:

• Detects installed Claude Code (claude --version) vs latest on npm (npm view @anthropic-ai/claude-code version)
• Detects local ClawCode HEAD vs upstream/main (when the plugin is a git checkout)
• Prints a compact comparison
• When updates are available, prints the safe procedure: explicit npm install -g, explicit git pull, explicit systemctl --user restart — the same atomic transition fix(service): wrap systemd ExecStart in PTY, disable auto-updater #9 wants users to take

What it deliberately doesn't do:

• Apply updates. The claude user typically can't write to /usr/local/lib/node_modules/ (root-owned), and even where it can, auto-applying updates from inside the runtime is exactly what fix(service): wrap systemd ExecStart in PTY, disable auto-updater #9 disabled. The skill detects and reports; the operator runs the printed commands themselves.

2. Heartbeat template gains an "Update check" bullet (templates/HEARTBEAT.md)

One line added. Heartbeat fires every 30 min, but the actual network calls are gated:

• Day-gate via memory/.last-update-check mtime — npm and GitHub don't need polling every 30 min, once per UTC day is plenty
• Per-version dedupe via memory/.notified-versions.json — each new version is announced exactly once, not every cycle

When a new version is detected, the heartbeat surfaces a short one-line ping with the safe command. Mobile-friendly, no code-block walls.

Why this pairs with #9

PR #9 turns off the unsafe automatic path. This PR provides the safe manual path and makes sure users don't forget about it. They make sense together; either one without the other is incomplete:

• fix(service): wrap systemd ExecStart in PTY, disable auto-updater #9 alone: users running ClawCode as a service silently fall behind on Claude Code updates because nothing surfaces "hey, there's a new version" anymore
• This PR alone: users still get the auto-update crash loop because the underlying DISABLE_AUTOUPDATER knob isn't set

I'd recommend landing them together. If they have to land separately, this one should land after #9 so the notification flow's first message isn't "you're 3 versions behind because we just turned off auto-update."

Permission constraints (worth flagging)

The skill is honest about what it can and can't do in different environments:

Setup	What works
Service running as root	Skill could in principle apply updates itself; this PR still doesn't (separation of concerns)
Service running as non-root, claude installed globally as root	Detection works; install commands need to be run by the operator (typical case — we recommend this)
Claude installed under user-owned npm prefix	Both detection and install would work; skill still detects-only

The "operator runs the command" pattern matches how a daemon should be operated — visible, explicit, audit-trail-able.

What's not changed

• No new code in lib/ — pure skill + template addition
• Existing agents' HEARTBEAT.md files are untouched (the template change applies to newly-created agents). Existing users who want the check can copy the bullet into their own HEARTBEAT.md.
• Skill doesn't touch any cron registry or harness state — it's a pure read flow

Test plan

• /agent:update from CLI: prints comparison block; prints update commands when versions differ; clean output when current
• /agent:update via Telegram: short response, uses *bold* not **bold**, no walls of bash
• No network: skill reports "unknown" for upstream values, doesn't error out
• No git remote upstream: ClawCode side reports unknown, Claude Code side still works
• Plugin not a git checkout: ClawCode side gracefully skipped, Claude Code side still works
• Heartbeat day-gate: second invocation within 24h skips network calls (verify by checking memory/.last-update-check mtime)
• Per-version dedupe: announcing version X writes to .notified-versions.json; subsequent heartbeats see X already-announced and stay quiet; new version Y triggers a new ping

🤖 Generated with Claude Code

[crisandrews]

Hey JD, love it, detect-only is the right call.

One thing before merge: the ClawCode version check fires on any upstream commit (step 4 does rev-parse upstream/main). Could you switch to git describe --tags so it only pings on real releases? A docs commit on main showing up as "update available" would just teach people to ignore the pings.

Rest looks solid. Thanks!

[JD2005L]

Good catch. Switched CW_UPDATE_AVAILABLE to tag-based. It now only fires when git describe --tags --abbrev=0 upstream/main differs from the local tag. Raw HEAD still renders in the diagnostic block for debugging but doesn't drive the notify signal anymore. Silent-check dedupe keys on the tag too, so each release is announced exactly once and chore/docs/ci traffic stays silent.

Pushed as 17e0423. Much better this way. Thanks!