@synadia-ai/agent-fabric-claude-code 0.2.0 → 0.3.1

package/skills/scratchpad/SKILL.md

@@ -26,7 +26,7 @@ shell command can then allow `scripts/sp` by its path, and does not ask.
 the NATS server, this agent's credentials, its workspace, its volume on
 `init`, the trace of the prompt you are serving, your address as the
 creator of what you publish, and the agent that prompted you as the grantee
-of a grant. Never pass `--url`, `--creds`, `--dir`, `--volume`,
+of a grant. Never pass `--url`, `--creds`, `--dir`, `--volume`, `--bootstrap-file`,
 `--thread-id`, `--root-id`, `--creator`, `--grantee-account` or
 `--grantee-user` yourself; `scripts/sp` refuses them.
 
@@ -39,8 +39,8 @@ The workspace is private to this agent and persists across restarts.
 Each successful command prints JSON.
 Read the returned receipt before reporting that publication succeeded.
 An upload alone does not publish a checkpoint.
-Retention preserves the root until explicit release.
-Its deadline permits later client cleanup.
+Retention preserves the root for its recorded promise.
+A finite deadline permits later cleanup by the client or the private lifecycle worker.
 A grant separately permits one authenticated principal to read that root and path.
 Do not print credential contents.
 
@@ -68,13 +68,27 @@ An expired reference or refused grant does not authorize another identity or pat
 
 ```sh
 scripts/sp info
-scripts/sp init --operation-id "$CREATE_ID"
+scripts/sp init
 scripts/sp describe
 ```
 
 `info` returns this agent's authenticated principal, owned scope allowances, and request limits.
 It needs no initialized workspace and changes no recovery state.
 The scope byte and object figures are configured allowances; `describe` shows current usage.
+
+### Import the configured bootstrap
+
+When `SCRATCHPAD_BOOTSTRAP_FILE` is configured, the wrapper supplies it on `init`.
+The public file selects one volume, admission binding, and complete saved creation Action.
+It contains no credentials and supplies no authentication authority.
+Run `scripts/sp init` without inventing a creation operation identifier.
+Keep both the file and the private workspace across restarts.
+An exact matching import preserves existing commands, writer state, and unknown outcomes.
+A different creation request refuses; an `exists` result never permits adoption.
+Saved creation recovery uses the owner's connection and does not need admin ensure.
+An expiry or closed refusal alone does not settle an earlier possibly sent creation.
+An explicit later admission needs a separate workspace; never erase the earlier one to continue.
+A configured custom volume must match the file. Unsupported command lines refuse the import.
 An empty scope list needs an operator admission check before this agent can publish.
 Volumes readable through another owner's grant are not listed; their granted references can still be read.
 If `info` reports an unknown command, an older binary was selected; continue with the existing commands and ask the operator for the allowances.
@@ -83,6 +97,10 @@ If `info` reports an unknown command, an older binary was selected; continue wit
 Rerun the saved creation action after an unknown outcome.
 An established writer whose journal disappeared requires an explicit reset.
 Initialization cannot silently reset that writer.
+For a reusable lifetime, `info` also returns its admission binding.
+`init` saves that binding before its first creation request and reuses it after a restart.
+A saved creation cannot adopt a later admission with the same volume name.
+Preserve the workspace after a refusal; do not erase it to bypass lifetime fencing.
 
 ## Publish a file and share it with the agent that prompted you
 
@@ -194,9 +212,12 @@ scripts/sp maintain --apply
 ```
 
 The first command reports the proposed maintenance.
-The second releases unprotected expired pins, closes the volume, traces retained dependencies, collects unreachable objects, and reopens it.
+The second releases unprotected expired pins and closes a collection interval.
+On a reusable deployment, private maintenance traces retained dependencies,
+collects unreachable objects and reopens that interval. The client observes its completion.
+On an existing deployment, the client performs that collection.
 Maintenance does not scrub retained file payloads.
-If interrupted, recover the saved request or repeat maintenance against the durable closed state.
+If interrupted, recover the saved request. A newer collection interval fences that request.
 Capacity refusal requires maintenance or an explicit operator decision; it never permits eviction of retained content.
 
 ## Capacity
@@ -207,3 +228,63 @@ Objects include chunks, file metadata, and directories.
 Retained results and unfinished uploads consume the same allowance.
 Replacing unique content needs room for both versions until old retention is released and collection completes.
 Local spools also need enough private disk space for the prepared artifact.
+
+### Choose what to remove at capacity
+
+On a reusable volume, `describe` includes `lifetime` with the lease, grace period,
+recovery-read state and reserved metadata allowance.
+Choose a path from the current head to remove. The service never chooses a live
+file to evict because the volume is full.
+
+```sh
+scripts/sp remove --path "$ARTIFACT_PATH" --operation-id "$REMOVE_ID"
+scripts/sp remove --path "$ARTIFACT_PATH" --operation-id "$REMOVE_ID" --apply
+```
+
+The first command reports a plan without changing the head.
+Applying saves the exact command and uses reserved metadata space within the reported bounds.
+The receipt confirms the new head. Retention or grants can still protect the removed content.
+Private maintenance returns space after that content is no longer protected.
+After an unknown result, use `recover`; do not change the saved path or operation identifier.
+Older binaries or deployments can refuse this command; that refusal does not permit eviction.
+
+### Keep or end a reusable lifetime
+
+A volume with `lifetime.expires_at` equal to zero is durable.
+For a managed lease, request one absolute Unix deadline in seconds:
+
+```sh
+scripts/sp renew --until "$UNTIL"
+```
+
+Save and retry the same deadline. Renewal must win before retirement begins.
+An already achieved renewal can still recover after that deadline passes.
+If recovery reports definite `expired` for an unachieved saved deadline, only the
+renewal intent is cleared. Request a new absolute deadline if the same lifetime is
+still renewable, then recover the unchanged ordinary pending operation.
+An unknown result keeps the saved renewal pending; do not replace its deadline.
+During recorded grace, recovery reads can remain available while ordinary writes are closed.
+Do not infer disposal authority from an agent disconnect, an idle volume, or full quota.
+
+Whole-volume retirement ends all head, retention, grant and access promises in its plan.
+It can permanently delete every artifact. Use it only when the user has authorized
+ending those promises and any required export has been restored and checked.
+
+```sh
+scripts/sp retire --operation-id "$RETIRE_ID"
+scripts/sp retire --operation-id "$RETIRE_ID" --end-promises --apply
+```
+
+Review the first result before applying. The exact terminal operation persists for recovery.
+If recovery proves a strictly newer nonterminal plan for the same incarnation,
+slot, generation, target, and saved request, it clears only the old release intent
+and reports `fenced`. The lifetime remains nonterminal. Inspect the reported
+lifetime and renew before ordinary work if needed. Review a new plan before
+applying again; this refusal does not mean that artifacts were disposed or capacity returned.
+Unknown or mismatched evidence and an already accepted terminal fence stay pending.
+`disposed` reports physical disposal; only `capacity_returned` confirms admission capacity is free.
+If a successor generation proves the old lifetime ended but this workspace never
+observed its own release fence, recovery also reports `acceptance_unknown: true`.
+That result confirms capacity return while leaving the original operation's acceptance unknown.
+Preserve the old workspace through completion. A later admission is a different lifetime,
+and old references and receipts do not select it.

package/skills/scratchpad/scripts/sp

@@ -50,7 +50,7 @@ refuse() {
 }
 
 # The command: the first argument that is not a flag or a flag's value, as
-# sp itself finds it. Every sp flag but --apply and --help takes a value.
+# sp itself finds it. --apply, --end-promises and --help take no value.
 # On the way, the operation id and the expiry, for the caller's grant after
 # a publication, and the reference, for the record of a grant.
 command=
@@ -70,7 +70,7 @@ for arg in "$@"; do
   fi
   case $arg in
     --) break ;;
-    -apply | --apply | -help | --help | -h) ;;
+    -apply | --apply | -end-promises | --end-promises | -help | --help | -h) ;;
     -*=*)
       name=${arg%%=*}
       case ${name#-} in
@@ -94,7 +94,7 @@ for arg in "$@"; do
   case $arg in
     -*)
       case $name in
-        url | creds | dir | volume | thread-id | root-id | tool-call-id | creator | grantee-account | grantee-user)
+        url | creds | dir | volume | bootstrap-file | thread-id | root-id | tool-call-id | creator | grantee-account | grantee-user)
           refuse "--$name is set by the agent, not passed; run the command without it" ;;
       esac
       ;;
@@ -102,12 +102,12 @@ for arg in "$@"; do
 done
 
 if [ -n "${SP_ENV_FILE:-}" ] && [ -f "$SP_ENV_FILE" ]; then
-  unset SP_THREAD_ID SP_ROOT_ID SP_CALLER_ACCOUNT SP_CALLER_USER
+  unset SP_THREAD_ID SP_ROOT_ID SP_CALLER_ACCOUNT SP_CALLER_USER SCRATCHPAD_VOLUME SCRATCHPAD_BOOTSTRAP_FILE
   while IFS= read -r line || [ -n "$line" ]; do
     case $line in
       *=*)
         case ${line%%=*} in
-          SP_NATS_URL | SP_NATS_CREDS | SCRATCHPAD_DIR | SCRATCHPAD_VOLUME | SP_CREATOR | \
+          SP_NATS_URL | SP_NATS_CREDS | SCRATCHPAD_DIR | SCRATCHPAD_VOLUME | SCRATCHPAD_BOOTSTRAP_FILE | SP_CREATOR | \
             SP_THREAD_ID | SP_ROOT_ID | SP_CALLER_ACCOUNT | SP_CALLER_USER | SP_GRANTS_FILE)
             # The name is one of these; the value is assigned as it is.
             eval "${line%%=*}=\${line#*=}"
@@ -150,8 +150,14 @@ fi
 
 case $command in
   init)
-    [ -n "${SCRATCHPAD_VOLUME:-}" ] || refuse "ScratchPad has no volume for this agent: SCRATCHPAD_VOLUME is unset"
-    set -- --volume "$SCRATCHPAD_VOLUME" "$@"
+    if [ -n "${SCRATCHPAD_BOOTSTRAP_FILE:-}" ]; then
+      set -- --bootstrap-file "$SCRATCHPAD_BOOTSTRAP_FILE" "$@"
+    else
+      [ -n "${SCRATCHPAD_VOLUME:-}" ] || refuse "ScratchPad has no volume or bootstrap file for this agent"
+    fi
+    if [ -n "${SCRATCHPAD_VOLUME:-}" ]; then
+      set -- --volume "$SCRATCHPAD_VOLUME" "$@"
+    fi
     ;;
   publish-file)
     if [ -n "${SP_CREATOR:-}" ]; then