c8ctl-plugin-nano 1.68.0 → 1.69.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -729,12 +729,11 @@ the job with a decremented retry count. Profiles are stored in the plugin's
729
729
  > `repository.sha`-detached checkout likewise recover nothing. For every transcript-only
730
730
  > run the resume preamble points at the transcript (VERIFY-first) rather than promising
731
731
  > a branch to check out.
732
- > - **Uncommitted working-tree changes are *not* recovered** in this increment —
732
+ > - **Uncommitted working-tree changes are *not* recovered** by default —
733
733
  > the throwaway workspace does not persist across activations, so any delta the
734
734
  > previous run had not committed is lost and the resumed agent re-derives it. The
735
- > resume preamble states this explicitly. (Persisting the workspace / microVM
736
- > across activations to recover uncommitted work is a later isolated-context
737
- > increment.)
735
+ > resume preamble states this explicitly. **WIP checkpoints** (below, on by default
736
+ > for pushing jobs) recover them.
738
737
  >
739
738
  > Resume is **best-effort and gated to external agent jobs** (the only ones with a
740
739
  > durable transcript). A read failure, an SDK without an AgentInstance read
@@ -747,6 +746,44 @@ the job with a decremented retry count. Profiles are stored in the plugin's
747
746
  > prompt (VERIFY-first, like the transcript), and a harness that advertises
748
747
  > `agentCapabilities._meta.planSeed` also receives it in `session/new` `_meta.plan`
749
748
  > so it can keep working the same plan. `NANO_AGENT_PLAN=off` disables both.
749
+ >
750
+ > **WIP checkpoints (`NANO_AGENT_CHECKPOINT=auto|on|off`, default `auto`).** The worker
751
+ > periodically snapshots the agent's workspace — uncommitted changes *and* unpushed local
752
+ > commits — to `refs/nano/wip/<elementInstanceKey>` on the job's remote, without touching
753
+ > the agent's HEAD, index or branch (a "shadow commit" built through a temporary index).
754
+ > `auto` enables this only for jobs that already publish their work: a provisioned,
755
+ > **authenticated** clone on a working branch with `branch.push` not `false` (read-only,
756
+ > anonymous, detached and repo-less jobs are skipped). `on` forces it for any provisioned
757
+ > job; `off` disables it.
758
+ >
759
+ > - **What is left out:** `.gitignore`d paths; secret-looking paths (`.env*`, `*.pem`,
760
+ > `id_*`, `.npmrc`, …); files over `NANO_AGENT_CHECKPOINT_MAX_FILE_BYTES` (5 MiB); and
761
+ > any changed file whose *content* contains one of the job's own injected secret
762
+ > values, the repo token, or a common credential format (private keys, GitHub / AWS /
763
+ > Slack / OpenAI-style tokens).
764
+ > - **When:** after a completed ACP tool call or plan change (at most one per
765
+ > `NANO_AGENT_CHECKPOINT_MIN_INTERVAL_MS`, default 60s), on a safety-net timer
766
+ > (`NANO_AGENT_CHECKPOINT_INTERVAL_MS`, default 300s, `0` disables — the only trigger for
767
+ > pipe/PTY harnesses), and once more when a run fails or is force-stopped. Each
768
+ > checkpoint also sets a best-effort local `agentCheckpoint {ref, sha, head, at, reason,
769
+ > branch}` variable on the element instance.
770
+ > - **Restore:** a later activation of the same element instance restores the snapshot
771
+ > into the fresh clone as uncommitted changes (recovering local commits too) and tells
772
+ > the agent to inspect `git status`/`git diff` first.
773
+ > - **Cleanup:** the ref is deleted once the engine acknowledges `job.complete` for a run
774
+ > whose branch push succeeded. Until that ack a lost lease or failed settle redelivers
775
+ > the job, so the ref stays restorable. Orphans (cancelled instances, failed acks,
776
+ > exhausted retries) are reclaimed by a background sweep (at most hourly per remote per
777
+ > worker) that deletes WIP refs older than `NANO_AGENT_CHECKPOINT_TTL_MS` (7 days), or
778
+ > older than 1h whose element instance the engine reports `COMPLETED`/`TERMINATED`.
779
+ > - **Safety:** pushes use `--force-with-lease`, so a superseded worker can't clobber a
780
+ > newer run's checkpoint. A remote *policy* refusal (repository rules, secret push
781
+ > protection) or a permission error stops checkpointing for that job with a warning;
782
+ > network errors are retried on the next trigger.
783
+ >
784
+ > Caveats: WIP refs are visible to anyone who can read the repo; the worker can't pause
785
+ > the agent, so a snapshot may catch a half-written file. Everything is best-effort — a
786
+ > failure degrades to transcript-only resume.
750
787
 
751
788
  > **Agent outcomes.** A harness may report an explicit end-of-task outcome in its
752
789
  > `session/prompt` result as `_meta.outcome` — `{ "status": "completed" | "blocked",