@lambdacurry/arbor 0.23.35 → 0.23.37

package/dist/arbor.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@lambdacurry/arbor",
-  version: "0.23.35",
+  version: "0.23.37",
   description: "The Arbor CLI — a shared workspace for people and agents. The human + headless-agent write path over Arbor's guarded operation surface.",
   keywords: [
     "agents",
@@ -11104,7 +11104,7 @@ var ORIENTATION_SECTIONS = [
   },
   {
     brief: null,
-    full: `Run \`arbor help\` (or read the MCP tool list) for the exact command/flags — those stay generated from the live action surface, so they're always current.`
+    full: `Run \`arbor help\` (or read the MCP tool list) for exact commands and flags. Computers are temporary: push Git work or publish/export a needed artifact outside them, suspend for an external wait, and finish the Run when done.`
   }
 ];
 var ORIENTATION = renderOrientation(ORIENTATION_SECTIONS);
@@ -11132,12 +11132,12 @@ var COMPUTER_ORIENTATION_SECTIONS = [
     full: `2. READ THE CAPABILITIES CARD, NOT THE BACKEND. runId is the one address: every runtime tool takes it, and the computerSessionId a Run carries is legacy input. computer_status(runId) describes the live PARENT Thread Computer behind a shared Run; it does not establish isolated Run activity, so use computer_run_receipt(runId) and computer_process_read for Run-owned work. Command-line utilities, including Git and package managers, run through computer_exec; check unfamiliar binaries with command -v.`
   },
   {
-    brief: "3. One Run per task; recover a lost response from the receipt before retrying; push work before finishing.",
-    full: `3. ONE RUN PER TASK. A write Run defaults to an isolated execution environment with its own filesystem, processes, ports, and /tmp while preserving /workspace paths; a read Run shares the parent. Pass runId to Run-aware tools. If a response is lost, recover the durable operation/process identity from computer_run_receipt and read it before retrying. computer_process_read settles a provider-absent current-generation process from exact evidence; computer_process_terminate sends one termination request and preserves the actual native terminal outcome from one bounded read. computer_run_suspend performs bounded settlement internally and never replays unknown work. A still-active process returns a retryable busy state; an unknown current-generation mutation fail-closes. An isolated local commit or Preview is not Git publication; push coherent work before computer_run_finish. discard=true with outcome failed or cancelled explicitly abandons Git work only after provider work is quiescent; it never overrides active or unknown execution.`
+    brief: "3. Computers are temporary: one Run per task; save work outside the Computer, then finish; suspend for a wait.",
+    full: `3. ONE RUN PER TASK. A write Run defaults to an isolated execution environment with its own filesystem, processes, ports, and /tmp while preserving /workspace paths; a read Run shares the parent. Pass runId to Run-aware tools. Ordinary shared foreground \`computer_exec\` is deliberately not journaled, so a missing receipt entry does not prove the command never executed. Retained shared journaling requires explicit \`background:true\` or \`waitForTerminalMs\` with container backing; use the same Run's \`computer_process_read\` with a bounded wait to observe it. If a response is lost, recover the durable operation/process identity from computer_run_receipt and read it before retrying. computer_process_read settles a provider-absent current-generation process from exact evidence; computer_process_terminate sends one termination request and preserves the actual native terminal outcome from one bounded read. computer_run_suspend performs bounded settlement internally and never replays unknown work. A still-active process returns a retryable busy state; an unknown current-generation mutation fail-closes. Save or publish needed work outside the temporary Computer before suspending or finishing; an isolated local commit or Preview is not Git publication, so push coherent work before computer_run_finish. discard=true with outcome failed or cancelled explicitly abandons Git work only after provider work is quiescent; it never overrides active or unknown execution.`
   },
   {
     brief: "4. Checkpoint complete units with `computer_run_suspend`; one `computer_run_finish` request is enough.",
-    full: `4. CHECKPOINT COMPLETE UNITS THROUGH THE RUN. computer_run_suspend(runId) checkpoints an intermediate complete unit — an isolated Run publishes its exact workspace and releases its Sandbox, a shared Run advances the parent lineage — and computer_run_finish(runId) requests the final release; finishing the last active shared Run also stops the parent. An accepted isolated finish may return status active with finishRequest.state pending while the lifecycle owner preserves output, verifies Git, checkpoints, and releases without caller cleanup; one request is sufficient, and computer_run_receipt is an optional observation rather than a progress trigger. A verified finishContinuation names the blocked stage and says callerAction none while that owner continues its capped retry. An isolated Run Preview is durable review output, not adoption or a checkpoint. The internal provider-handle publication operations are not agent tools.`
+    full: `4. CHECKPOINT COMPLETE UNITS THROUGH THE RUN. computer_run_suspend(runId) checkpoints an intermediate complete unit — an isolated Run publishes its exact workspace and releases its Sandbox, while a shared Run checkpoints the parent without releasing it — and the same runId resumes later. A normal shared computer_run_finish(runId) checkpoints the parent and stops it when this is the last active shared Run; shared discard with outcome=cancelled or failed closes only the Run record, without checkpointing, stopping shared processes, or preserving unread output. Isolated discard abandons its workspace after the existing quiescence checks. An accepted isolated finish may return status active with finishRequest.state pending while the lifecycle owner preserves output, verifies Git, checkpoints, and releases without caller cleanup; one request is sufficient, and computer_run_receipt is an optional observation rather than a progress trigger. For example: suspend run_… while waiting for CI, then call computer_run_receipt or computer_exec with that same runId after CI and finish it; do not create a replacement Run. A verified finishContinuation names the blocked stage and says callerAction none while that owner continues its retry. An isolated Run Preview is durable review output, not adoption or a checkpoint. The internal provider-handle publication operations are not agent tools.`
   },
   {
     brief: "5. Git and gh run through `computer_exec` once authorized; fetch before trusting remote state.",
@@ -11934,7 +11934,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_start",
     title: "Start a run",
-    description: `Start an isolated write Run or shared/read Run with one idempotencyKey; a pending admission returns runStartId for receipt observation while the lifecycle owner continues independently, and caller work waits for admission. First use: read the Computer guide at ${AGENT_GUIDE_URLS.computer}.`,
+    description: `Start an isolated write Run or shared/read Run with one idempotencyKey; pending admission returns runStartId for receipt observation while the lifecycle owner continues independently. Save work outside the temporary Computer and finish the Run when done; first use: read the Computer guide at ${AGENT_GUIDE_URLS.computer}.`,
     inputSchema: {
       threadId: string2().optional().describe("the Thread whose Computer this Run works in, thr_…; the canonical Run-first front door"),
       computerSessionId: string2().optional().describe("legacy compatibility alternative to threadId: an existing parent computerSessionId, cms_…"),
@@ -11954,7 +11954,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_suspend",
     title: "Suspend a run",
-    description: "Checkpoint an active WRITE Run for an external wait: isolated Runs publish their exact workspace and release the Sandbox; shared Runs checkpoint the parent, and the same runId resumes next. Preserves unread terminal output internally for 30 days; no caller drain is required, larger captures use bounded same-Run retries, and active/unknown work or failed preservation blocks release without replay.",
+    description: "Checkpoint an active WRITE Run for an external wait: save or publish needed work outside the Computer first; shared Runs checkpoint the parent without releasing it, while isolated Runs publish their exact workspace and release the Sandbox; resume with the same runId. Unread terminal output is retained for 30 days; no drain required; active/unknown work or failed preservation blocks release.",
     inputSchema: {
       runId: string2().describe("the active WRITE Run to suspend, run_…")
     },
@@ -11976,7 +11976,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_finish",
     title: "Finish a run",
-    description: "Request final Run release with unread terminal output preserved for 30 days. An isolated Run may return status active with finishRequest pending while its lifecycle owner proves quiescence, Git durability, checkpoint, and release without caller cleanup; send once, observe the receipt optionally, and use discard=true with failed or cancelled only to abandon Git after provider quiescence.",
+    description: "Finish after saving/publishing needed work outside the Computer; shared finish checkpoints parent and stops last shared Run; shared discard with failed/cancelled only closes record (no checkpoint, shared stop, unread preservation); isolated discard abandons workspace after quiescence. May stay pending for quiescence, durability, checkpoint, release; discard=true requires failed/cancelled.",
     inputSchema: {
       runId: string2().describe("the runId returned by computer_run_start, run_…"),
       outcome: _enum(["finished", "failed", "cancelled"]).optional().describe("terminal outcome; defaults to finished"),
@@ -11990,7 +11990,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_receipt",
     title: "Read a run receipt",
-    description: "Read with exactly one of runId or runStartId: observe pending admission, finish continuation, Run-owned operation/activity state, and providerLifecycle instead of parent computer_status. Reads never drive admission or finish; setupReadiness observes declared-setup match and is not an instruction to reinstall — run computer_run_setup when the task needs a prepared workspace.",
+    description: "Read pending admission, finish continuation, Run-owned operation/activity state, and providerLifecycle with exactly one of runId or runStartId instead of parent computer_status. This read drives nothing; setupReadiness is not an instruction to reinstall: run computer_run_setup when the task needs a prepared workspace, then save work outside the temporary Computer before finishing.",
     inputSchema: {
       runId: string2().optional().describe("the Run to read, run_…; provide exactly one of runId or runStartId"),
       runStartId: string2().optional().describe("the pending or linked RunStart to read, rsr_…; alternative to runId")
@@ -12054,7 +12054,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_exec",
     title: "Run a command",
-    description: "Run a shell command in runId with ambient GitHub authorization; timeout kills the process. Use waitForTerminalMs for immediate or bounded native observation, then continue with computer_process_read and nextCursor for a truncated output page; background is mutually exclusive, and after response loss read computer_run_receipt.operations[].operationId instead of repeating the mutation.",
+    description: "Run a shell command in runId with ambient GitHub authorization; timeout kills the process, so save results outside this Computer and finish the Run when done. Use waitForTerminalMs, then computer_process_read with nextCursor for a truncated output page; background is mutually exclusive, and after response loss read computer_run_receipt.operations[].operationId instead of repeating the mutation.",
     inputSchema: {
       computerSessionId: string2().optional().describe("legacy alternative to runId: a computerSessionId on that Computer, cms_…; required unless runId is supplied"),
       command: string2().min(1).describe("the shell command to run"),
@@ -12104,7 +12104,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_status",
     title: "Inspect a computer",
-    description: "Inspect the live PARENT Thread Computer behind runId: capabilities, live can-I-exec readiness, processes, and profile. It does not report isolated Run command state (computer_run_receipt) or restore-safety (get_computer); transient unavailability drops command capabilities, and a terminal unknown mutation is a non-retryable stop.",
+    description: "Inspect the live PARENT Thread Computer behind runId for capabilities, can-I-exec readiness, processes, and profile; save needed work outside this temporary Computer. It does not report isolated Run command state (computer_run_receipt) or restore-safety (get_computer); transient unavailability drops command capabilities, and a terminal unknown mutation is a non-retryable stop.",
     inputSchema: {
       runId: string2().optional().describe("the Run whose parent Computer to inspect, run_…"),
       computerSessionId: string2().optional().describe("legacy alternative to runId: a computerSessionId on that Computer, cms_…")
@@ -15735,7 +15735,7 @@ async function renderMe(ctx, action) {
 ` : "") + spaceLines;
   emitDual(me, human, action, ctx);
 }
-var CLI_NOTE = `On this CLI, before your first write: commands are NOUN-VERB (\`thread get\`, \`space get\`, not \`get thread\`). The underscore tool-names you see in MCP, recall, and docs (\`set_space_charter\`, \`transition_thread\`) work as CLI commands VERBATIM too — \`set_space_charter …\` and \`set space charter …\` are the same command, either form. Computer work is Run-first: start project work with \`arbor computer run start --thread-id thr_… --mode write --idempotency-key scope-run-1\`, reuse that key only for the same logical Run, keep its runId, and pass \`--run-id run_…\` to later commands such as \`computer run suspend --run-id run_…\`, \`computer run finish --run-id run_…\`, and \`computer run receipt --run-id run_…\`. Checkpoint intermediate complete units; make one durable finish request, and read the receipt when you need the result. Finish and suspend preserve unread terminal output internally, so no caller drain is required. A public screenshot is lighter: \`arbor computer verify --thread-id thr_… --target-url https://…\` runs directly without starting a Run, and returns a gated download URL plus ready-to-place Markdown; put that Markdown where the image belongs in the contribution body and pass the matching attachment id. A single-argument command also takes a bare positional — \`recall "your question"\`, \`thread get thr_…\` — so you don't have to name the obvious flag. Flag names are kebab-derived from the inputs (\`--thread-id\`, \`--request-id\`, \`--contribution-id\` — not \`--thread\`/\`--request\`), so check \`arbor help\` or \`arbor <command> --help\` (now focused on that command's flags) instead of guessing. Pass long/markdown bodies via \`--body-file -\` (stdin), never shell-quoted; a one-line \`--summary\` (1-2 short sentences, hard limit 500 chars) on a long contribution becomes its recall snippet. List inputs always accept a REPEATED flag, one item each (\`--guidance "…" --guidance "…"\`) — the form that works everywhere. A single value additionally comma-splits for TOKEN lists (\`--capabilities a,b,c\`), but stays one literal item for PROSE lists (\`--guidance\`, \`--ways-to-help\`, \`--contribution-lanes\`) so a comma inside a sentence can't shred it; \`arbor <command> --help\` names which form each list flag takes. \`tree\` is the lifecycle map (default depth \`topics\`, external page 4): choose a Topic, then \`recall --topic top_… "your question"\` before targeted \`thread get\`/\`artifact get\`; continue with \`--cursor\`, use \`--all\` only for intentional complete enumeration, and scope \`--depth threads\` to one Space or Topic. If \`inbox\` is empty, that's "nothing needs you" — but if you're unsure your auth resolved, \`whoami\` confirms it.`;
+var CLI_NOTE = `On this CLI, before your first write: commands are NOUN-VERB (\`thread get\`, \`space get\`, not \`get thread\`). The underscore tool-names you see in MCP, recall, and docs (\`set_space_charter\`, \`transition_thread\`) work as CLI commands VERBATIM too — \`set_space_charter …\` and \`set space charter …\` are the same command, either form. Computer work is Run-first: start project work with \`arbor computer run start --thread-id thr_… --mode write --idempotency-key scope-run-1\`, reuse that key only for the same logical Run, keep its runId, and pass \`--run-id run_…\` to later commands such as \`computer run suspend --run-id run_…\`, \`computer run finish --run-id run_…\`, and \`computer run receipt --run-id run_…\`. Computers are temporary: push Git work or publish/export a needed artifact outside them; suspend for a wait and make one durable finish request when done. Read the receipt when you need the result. Finish and suspend preserve unread terminal output internally, so no caller drain is required. A public screenshot is lighter: \`arbor computer verify --thread-id thr_… --target-url https://…\` runs directly without starting a Run, and returns a gated download URL plus ready-to-place Markdown; put that Markdown where the image belongs in the contribution body and pass the matching attachment id. A single-argument command also takes a bare positional — \`recall "your question"\`, \`thread get thr_…\` — so you don't have to name the obvious flag. Flag names are kebab-derived from the inputs (\`--thread-id\`, \`--request-id\`, \`--contribution-id\` — not \`--thread\`/\`--request\`), so check \`arbor help\` or \`arbor <command> --help\` (now focused on that command's flags) instead of guessing. Pass long/markdown bodies via \`--body-file -\` (stdin), never shell-quoted; a one-line \`--summary\` (1-2 short sentences, hard limit 500 chars) on a long contribution becomes its recall snippet. List inputs always accept a REPEATED flag, one item each (\`--guidance "…" --guidance "…"\`) — the form that works everywhere. A single value additionally comma-splits for TOKEN lists (\`--capabilities a,b,c\`), but stays one literal item for PROSE lists (\`--guidance\`, \`--ways-to-help\`, \`--contribution-lanes\`) so a comma inside a sentence can't shred it; \`arbor <command> --help\` names which form each list flag takes. \`tree\` is the lifecycle map (default depth \`topics\`, external page 4): choose a Topic, then \`recall --topic top_… "your question"\` before targeted \`thread get\`/\`artifact get\`; continue with \`--cursor\`, use \`--all\` only for intentional complete enumeration, and scope \`--depth threads\` to one Space or Topic. If \`inbox\` is empty, that's "nothing needs you" — but if you're unsure your auth resolved, \`whoami\` confirms it.`;
 function renderOrient(ctx) {
   emitDual({ orientation: ORIENTATION, cliNote: CLI_NOTE }, `${ORIENTATION}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambdacurry/arbor",
-  "version": "0.23.35",
+  "version": "0.23.37",
   "description": "The Arbor CLI — a shared workspace for people and agents. The human + headless-agent write path over Arbor's guarded operation surface.",
   "keywords": [
     "agents",