Loading
Transactionally update a customized NanoClaw checkout from official upstream without exposing live mounted source, with fork-safe skill refresh, mutable-state snapshots, migration gates, exact-code up
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add nanocoai/nanoclaw --skill update-nanoclaw -a cursor -y
Transactionally update a customized NanoClaw checkout from official upstream without exposing live mounted source, with fork-safe skill refresh, mutable-state snapshots, migration gates, exact-code upgrade markers, detected service restart, health verification, and automatic local rollback. Use for routine merge, rebase, or selective upstream updates.
Transactionally update a customized NanoClaw checkout from official upstream without exposing live mounted source, with fork-safe skill refresh, mutable-state snapshots, migration gates, exact-code upgrade markers, detected service restart, health verification, and automatic local rollback. Use for routine merge, rebase, or selective upstream updates.
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.
.env, data/, groups/, store/, and manual-service state before
cutover. Sockets and other ephemeral special files are intentionally omitted.data/ncl.sock, and bin/ncl groups list.pnpm dev/Node host is running. Stop that
process explicitly, update offline, then start it again manually.Confirm the live tree is clean:
git status --porcelain
Stop if it prints anything. Setup commits the files it applies as
setup: apply <skill> commits unless NANOCLAW_SETUP_COMMIT=0 was set.
Treat anything left as part of the install: show it, ask the user to commit it
as a local customization, then re-check. Never stash it, since the updater
discovers installed skills from these files.
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.
The controller always comes from main; the ref it merges follows the channel
(step 2).
# 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"
Channels (NANOCLAW_UPDATE_CHANNEL in .env; --channel <name> overrides it
once): stable (default) = newest annotated vX.Y.Z tag; beta = newest
-rc.N if newer than stable; edge = upstream main. Change the default only
with set-channel (below), never by editing .env.
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" --remote "$upstream_remote" --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.
Tell the user the channel and upstreamRef. Then:
Nothing new (stable/beta, phase: prepared, targetHead equals
originalHead): say "Already on the newest release (vX.Y.Z)", still run
step 3 (it refreshes installed skills), and abandon if targetHead is
still unchanged.
Error code: ahead-of-release (nothing staged): ask once, "This install
is newer than the latest release, <tag>. Keep getting the newest code from
main (edge), or switch to releases and wait for the next one (stable)?"
Save the answer, then on edge re-run prepare with --channel edge; on
stable stop, as there is nothing to update until the next release:
pnpm exec tsx "$controller_dir/scripts/update-nanoclaw.ts" set-channel \
--project-root "$PWD" --channel edge # or stable
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 $controller_dir, not from stageRoot: a
cherry-pick stage can still hold the old controller. If $controller_dir 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"
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, and of the selected gateway when gateway core or that gateway's
own skill changed. On a skill-only change, a gateway it cannot resolve is
skipped and named in the validation checks. It 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.
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.
Process requirements one at a time.
/<skill>, read that skill's current SKILL.md and follow
it directly. Do not require a harness-specific skill invocation feature.docs/onecli-upgrades.md; record the exact old
version or rollback command because OneCLI is outside the Git snapshot.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.
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.
After success, remove the staging worktree and its temporary branch from the live checkout. This keeps the backup branch/tag and mutable snapshot intact for rollback:
pnpm exec tsx scripts/update-nanoclaw.ts cleanup --id "$id"
If health fails, the controller restores the previous Git commit and mutable state, rebuilds the previous image, restarts the old service, and verifies it. If an external component was changed, also execute the recorded external rollback instruction and verify that component; Git cannot restore it.
Report:
Manual rollback remains available while the snapshot is retained:
pnpm exec tsx scripts/update-nanoclaw.ts rollback --id "$id"
Do not describe the Git tag alone as full rollback. The transaction snapshot is what restores SQLite and other mutable local state. Keep the newest successful transaction until the next update completes. Then preview older terminal transactions that are safe to prune:
pnpm exec tsx scripts/update-nanoclaw.ts prune --id "$id" --dry-run
Show the removed list and ask for confirmation. If confirmed, run the same
command without --dry-run. Pruning keeps the selected transaction, every
newer transaction, and every nonterminal transaction. It removes older terminal
snapshots and their staging/backup Git references. Never delete transaction
directories directly.