update-nanoclaw skill

Update NanoClaw

Update a customized install through an isolated, resumable transaction. The live checkout is not touched until the staged result has passed validation.

Use ordinary conversation for decisions and confirmations. Do not depend on Claude Code, Codex, OpenCode, or any provider-specific question/skill tool.

Safety contract

tests in a separate worktree.

• Require a clean live checkout.
• Stage Git integration, dependency installation, installed-skill refresh, and

changing source mounted into agent containers.

• Resolve registry branches from the remote that actually carries them.
• Stop the detected service and drain this install's active containers before

cutover. Sockets and other ephemeral special files are intentionally omitted.

• Snapshot .env, data/, groups/, store/, and manual-service state before

mode; require process state, data/ncl.sock, and bin/ncl groups list.

• Gate every breaking migration and external version-pin move.
• Stamp the exact Git commit/tree only after all required work succeeds.
• Restart through the detected launchd, user-systemd, system-systemd, or nohup

process explicitly, update offline, then start it again manually.

• Refuse cutover while an unmanaged pnpm dev/Node host is running. Stop that

the previous image, restart the previous service, and health-check it.

• On build or health failure, restore Git and the mutable-state snapshot, rebuild

1. Load the newest controller without changing the live tree

Confirm the live tree is clean:

git status --porcelain

Stop if it prints anything.

Use the official remote if one already exists. Otherwise add it as upstream:

if git remote get-url upstream >/dev/null 2>&1; then
  upstream_remote=upstream
elif git remote get-url origin 2>/dev/null | grep -Eq '(^|[:/])nanocoai/nanoclaw(.git)?$'; then
  upstream_remote=origin
else
  git remote add upstream https://github.com/nanocoai/nanoclaw.git
  upstream_remote=upstream
fi
git fetch "$upstream_remote" --prune

Select main when present, otherwise master:

if git show-ref --verify --quiet "refs/remotes/$upstream_remote/main"; then
  upstream_ref="$upstream_remote/main"
elif git show-ref --verify --quiet "refs/remotes/$upstream_remote/master"; then
  upstream_ref="$upstream_remote/master"
else
  echo "Official remote has neither main nor master" >&2
  exit 1
fi

Materialize the newest controller from that ref. This is the self-update seam: an older local skill still executes the newest safety code before any mutation.

# pwd -P: on macOS mktemp returns a path through the /var symlink, and a
# symlinked argv defeats Node's import.meta main-module guard — the controller
# then exits 0 having done NOTHING. Canonicalize before use.
controller_dir="$(cd "$(mktemp -d)" && pwd -P)"
# Extract all of scripts/, not a hand-listed subset. These paths are a
# contract: older copies of this skill extract exactly them from the newest
# ref, so the controller must load from them alone, with no node_modules.
# scripts/update/controller-archive.test.ts enforces it.
git archive "$upstream_ref" scripts src/install-slug.ts | tar -x -C "$controller_dir"

2. Choose the Git strategy and prepare

Default to merge. Use rebase only when the user explicitly wants linear history. Use cherry-pick only with an explicit comma-separated commit list.

pnpm exec tsx "$controller_dir/scripts/update-nanoclaw.ts" prepare \
  --project-root "$PWD" --upstream-ref "$upstream_ref" --strategy merge

The JSON result is nanoclaw-update/v1. Record its id, stageRoot, backup branch/tag, changed files, and requirements. The live HEAD is still unchanged.

If phase is conflict, resolve conflicts only inside stageRoot, preserving intentional local customizations. Complete the merge/rebase/cherry-pick there, commit it, then run:

pnpm exec tsx "$controller_dir/scripts/update-nanoclaw.ts" resume \
  --project-root "$PWD" --id "$id"

Run every transaction command from $controllerdir, not from stageRoot: a cherry-pick stage can still hold the old controller. If $controllerdir is gone (a reboot clears temp directories), recreate it with the step 1 commands without fetching again.

Show the user the upstream commits, changed-file buckets, requirements, and any resolved conflicts. To stop with no live mutation:

pnpm exec tsx "$controller_dir/scripts/update-nanoclaw.ts" abandon \
  --project-root "$PWD" --id "$id"

3. Validate the staged result

pnpm exec tsx "$controller_dir/scripts/update-nanoclaw.ts" validate \
  --project-root "$PWD" --id "$id"

Validation performs a fork-safe structured refresh of every installed channel and provider, commits refreshed payloads in the staging branch, installs frozen dependencies, runs the host build and full host tests, and runs the container dependency/typecheck leg when Bun is available. A provider skill that declares Bun dependencies does not require Bun on the host: refresh runs the exact Bun version pinned by container/Dockerfile through pnpm. Any selected skill refresh or validation failure blocks cutover and the completion stamp.

Fix only failures caused by the staged update, inside stageRoot, commit the fix, and re-run validation. Do not mutate the live checkout to repair staging.

4. Confirm and cut over

Before downtime, show the exact changed files, required migrations, detected backup tag, and rollback command. Ask for one confirmation to begin cutover.

pnpm exec tsx "$controller_dir/scripts/update-nanoclaw.ts" cutover \
  --project-root "$PWD" --id "$id"

Cutover stops the detected service, then stops this install's labeled agent containers (an agent mid-turn loses that turn; wait for a quiet moment if that matters), snapshots mutable state, resets the live branch to the validated target, installs frozen dependencies, builds the host, and updates the agent image when container/ changed. Hardened-image installs use pull; local-image installs build locally. The service remains stopped while required migrations are pending.

5. Complete every requirement

Process requirements one at a time.

its detect, fix, verify, and rollback sections.

• For a referenced local guide, read it from the cut-over checkout and follow

it directly. Do not require a harness-specific skill invocation feature.

• For a referenced /, read that skill's current SKILL.md and follow

version or rollback command because OneCLI is outside the Git snapshot.

• For OneCLI pin moves, follow docs/onecli-upgrades.md; record the exact old

If a migration intentionally changes tracked files, review and commit those changes before acknowledging it. Finish refuses a dirty cut-over checkout.

After verification, acknowledge the requirement:

pnpm exec tsx "$controller_dir/scripts/update-nanoclaw.ts" ack \
  --project-root "$PWD" --id "$id" \
  --requirement "$requirement_id" --status succeeded

For an external component, also pass a concise exact rollback instruction:

... ack ... --rollback "restore onecli-gateway to <old-version>"

Use --status failed when verification fails. A pending or failed requirement blocks finish; never offer “restart anyway.” The state snapshot is the recovery path for forward local migrations.

6. Finish and health-check

pnpm exec tsx "$controller_dir/scripts/update-nanoclaw.ts" finish \
  --project-root "$PWD" --id "$id"

Finish stamps the exact version/commit/tree, restarts the service mode detected before cutover, and waits for the process, CLI socket, and a real CLI request. Only phase: complete is success.