@lambdacurry/arbor 0.24.4 → 0.24.7

package/dist/arbor.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@lambdacurry/arbor",
-  version: "0.24.4",
+  version: "0.24.7",
   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",
@@ -8285,6 +8285,7 @@ var OPERATION_LOSS_REASONS = new Set([
 
 // ../core/src/ops/computer-run-retention.ts
 var COMPUTER_RUN_RETENTION_WARNING_MS = 24 * 60 * 60 * 1000;
+var COMPUTER_RUN_SUSPENDED_EXPIRY_MS = 24 * 60 * 60 * 1000;
 
 // ../core/src/ops/computer-run.ts
 var COMPUTER_RUN_START_CHECKPOINT_RESERVATION_STALE_MS = 12 * 60 * 1000;
@@ -8303,6 +8304,23 @@ var COMPUTER_RUN_F1_FINAL_FAILURE_CODES = new Set([
 ]);
 var TERMINAL = new Set(["finished", "failed", "cancelled"]);
 var RUN_LIFECYCLE_TYPES = new Set(["run.started", "run.finished", "run.failed", "run.cancelled"]);
+var RUN_BOOKEND_STAND_INS = new Set([
+  "n/a",
+  "na",
+  "none",
+  "null",
+  "undefined",
+  "todo",
+  "tbd",
+  "placeholder",
+  "test",
+  "foo",
+  "bar",
+  "asdf",
+  "ok",
+  "okay",
+  "done"
+]);
 var COMPUTER_RUN_RECOVERY_WINDOW_MS = 60 * 60 * 1000;
 var COMPUTER_RUN_OWNER_DECISION_WINDOW_MS = 24 * 60 * 60 * 1000;
 var COMPUTER_RUN_FINISH_PUBLICATION_UNVERIFIED_MS = 2 * 60 * 60 * 1000;
@@ -11250,7 +11268,7 @@ var ORIENTATION_SECTIONS = [
   },
   {
     brief: null,
-    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.`
+    full: `Run \`arbor help\` (or read the MCP tool list) for exact commands and flags. Start Runs with a short intention; suspend if you need the workspace again, finish with an accomplishments summary when done with it. Current Git-publication and safety guards still apply.`
   }
 ];
 var ORIENTATION = renderOrientation(ORIENTATION_SECTIONS);
@@ -11271,19 +11289,19 @@ var COMPUTER_ORIENTATION_SECTIONS = [
   },
   {
     brief: "1. Start with `get_computer(threadId)`; authorize repos narrowly; `computer_run_start` is the front door; read the repo's AGENTS.md before editing.",
-    full: `1. ORIENT, CONFIGURE, AND AUTHORIZE. Start with provider-free get_computer(threadId) to inspect the effective inherited recipe, repository authorization, compatibility, recoverySafety, and durable lineage without contacting execution. Use set_organization_computer, set_space_computer, set_topic_computer, or set_thread_computer only when the corresponding complete sparse layer must be replaced; use github_connect_repository with a known installed id, exact owner/name, or canonical GitHub URL, or use github_repositories when browsing, to authorize repositories at the narrowest scope that should inherit them. If github_repositories looks stale, github_refresh_installation reconciles the cached inventory from GitHub. computer_run_start(threadId, mode) is the front door: it attaches durable identity itself and starts an isolated write Run from the Thread's base snapshot without booting the parent. Each returned repository entry includes verified root instruction pointers when that repo has an AGENTS.md: read surfaced repository instructions before substantial edits or verification, then check for a nearer nested AGENTS.md once the target path is known. Repo-local instructions/scripts/config beat guessed formatter, test, lint, or build commands.`
+    full: `1. ORIENT, CONFIGURE, AND AUTHORIZE. Start with provider-free get_computer(threadId) to inspect the effective inherited recipe, repository authorization, compatibility, recoverySafety, and durable lineage without contacting execution. Use set_organization_computer, set_space_computer, set_topic_computer, or set_thread_computer only when the corresponding complete sparse layer must be replaced; use github_connect_repository with a known installed id, exact owner/name, or canonical GitHub URL, or use github_repositories when browsing, to authorize repositories at the narrowest scope that should inherit them. If github_repositories looks stale, github_refresh_installation reconciles the cached inventory from GitHub. computer_run_start with threadId, mode, label and idempotencyKey is the front door: it attaches durable identity itself and starts an isolated write Run from the Thread's base snapshot without booting the parent. Each returned repository entry includes verified root instruction pointers when that repo has an AGENTS.md: read surfaced repository instructions before substantial edits or verification, then check for a nearer nested AGENTS.md once the target path is known. Repo-local instructions/scripts/config beat guessed formatter, test, lint, or build commands.`
   },
   {
     brief: "2. `runId` is the one address; use `computer_run_receipt` and `computer_process_read` for Run-owned work.",
     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. 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: "3. State Run intent in label; suspend to return to its workspace, finish with a summary when done with it.",
+    full: `3. ONE OWNER PER RUN. State a short intention in label at start and an accomplishments summary in reason at finish; later calls need only runId, without repeated narration. 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. Suspend if you need this workspace again; finish intentionally ends the segment and releases isolated execution. Save work outside the Computer for independent durability. Current isolated finish still requires Git publication; an isolated local commit or Preview does not satisfy that gate. 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, 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.`
+    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, reason }) 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.",
@@ -12052,7 +12070,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "attach_computer",
     title: "Attach a Thread computer",
-    description: "Deprecated by AD-306: computer_run_start(threadId) attaches durable identity itself, so use this only to mint protocol identity with no Run at all. Creates or reuses the Thread's stable Computer identity and an immutable collaborator receipt without starting provider runtime.",
+    description: "Deprecated by AD-306: computer_run_start attaches durable identity itself, so use this only to mint protocol identity with no Run at all. Creates or reuses the Thread's stable Computer identity and an immutable collaborator receipt without starting provider runtime.",
     inputSchema: {
       threadId: string2().describe("the Thread whose computer you are attaching, thr_… or a short id like BUD-34")
     },
@@ -12063,7 +12081,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_open",
     title: "Open a Thread computer",
-    description: "Deprecated by AD-306: start work with computer_run_start(threadId, mode) instead; this alias remains one release and boots the parent Thread Computer, returning a computerSessionId. An optional owned active runId records a successful session attach as Run retention activity. Use it only for a legacy client that still addresses the parent by cms_ id; unsafe recovery is refused and unresolved newer workspace state stays fail-closed.",
+    description: "Deprecated by AD-306: start work with computer_run_start instead; this alias remains one release and boots the parent Thread Computer, returning a computerSessionId. An optional owned active runId records a successful session attach as Run retention activity. Use it only for a legacy client that still addresses the parent by cms_ id; unsafe recovery is refused and unresolved newer workspace state stays fail-closed.",
     inputSchema: {
       threadId: string2().describe("the Arbor Thread whose stable computer to open, thr_… or a short id like BUD-34"),
       runId: string2().optional().describe("optional owned active Run; successful open renews its retention deadline"),
@@ -12091,13 +12109,13 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_start",
     title: "Start a run",
-    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}.`,
+    description: `Start isolated write or shared/read work with a short intention in label and one idempotencyKey; pending admission returns runStartId. Suspend if you need this workspace again; finish with an accomplishments summary when done, subject to current Git/safety guards; 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_… or a short id like BUD-34; the canonical Run-first front door"),
       computerSessionId: string2().optional().describe("legacy compatibility alternative to threadId: an existing parent computerSessionId, cms_…"),
       mode: _enum(["read", "write"]).describe("write for mutable work; read for shared inspection"),
       execution: _enum(["shared", "isolated"]).optional().describe("write Run placement; defaults to isolated. Use shared only for intentional live collaboration on the Thread Computer"),
-      label: string2().max(120).optional().describe("short factual label for this unit of work"),
+      label: string2().trim().max(120).optional().describe("required for a new Run: short actual intention, e.g. Fix CI; exact accepted legacy retries reuse their original text or omission"),
       requestedRevisions: array(object({
         repository: string2().describe("configured GitHub repository as canonical owner/name"),
         head: string2().regex(/^[0-9a-fA-F]{40}(?:[0-9a-fA-F]{24})?$/).describe("exact 40- or 64-hex Git object id required before caller work")
@@ -12111,7 +12129,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_suspend",
     title: "Suspend a run",
-    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.",
+    description: "Preserve an active WRITE Run and its workspace when you expect to return; shared Runs checkpoint the parent, isolated Runs publish their exact workspace and release the Sandbox; resume with the same runId within 24h or an unkept isolated Run ends. 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_…")
     },
@@ -12133,11 +12151,11 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_finish",
     title: "Finish a run",
-    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.",
+    description: "End this Run with an accomplishments summary when done with its workspace; suspend if you expect to return. Current isolated finish requires Git durability; shared finish checkpoints/stops last shared Run; shared discard closes only record; isolated discard abandons 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"),
-      reason: string2().max(500).optional().describe("one factual line on how this unit of work ended, e.g. what shipped or what broke"),
+      reason: string2().trim().max(500).optional().describe("required for a new finish intent: accomplishments and useful outcomes or limits; exact accepted legacy retries reuse their original text or omission"),
       discard: boolean2().optional().describe("explicitly abandon non-durable Git or workspace state only after provider quiescence; requires outcome failed or cancelled and never overrides active or unknown execution")
     },
     surfaces: ["computer-mcp", "computer-cli"],
@@ -12159,7 +12177,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_retention",
     title: "Inspect Run retention",
-    description: "Report the deadline, last meaningful use, Keep flag, and advisory warning for one isolated Run. Expiry is disabled; this read sends no warning and releases nothing.",
+    description: "Report the deadline, last meaningful use, Keep flag, and advisory warning for one isolated Run; a suspended Run is due 24 hours after it suspended. This read sends no warning and releases nothing.",
     inputSchema: {
       runId: string2().describe("the Run to inspect, run_…")
     },
@@ -12170,7 +12188,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_keep",
     title: "Keep Run data",
-    description: "The Run owner or an organization admin can set or clear Keep for a newly created isolated Run, using expectedRevision to guard races. It protects restorable Run data without keeping provider compute alive; expiry remains disabled.",
+    description: "The Run owner or an organization admin can set or clear Keep for a newly created isolated Run, using expectedRevision to guard races. It protects restorable Run data without keeping provider compute alive; Keep stops a suspended Run from ending on its own after 24 hours.",
     inputSchema: {
       runId: string2().describe("the Run to protect, run_…"),
       keep: boolean2().describe("true to retain the Run's restorable data; false to resume the policy"),
@@ -12545,7 +12563,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_stop",
     title: "Checkpoint and stop",
-    description: "Deprecated by AD-306: finishing the last active shared Run with computer_run_finish(runId) performs the final checkpoint and stops the parent. Still checkpoints and stops the parent for a shared write Run (runId) or a legacy computerSessionId, refusing teardown when durability fails or a background process is running.",
+    description: "Deprecated by AD-306: finishing the last active shared Run with computer_run_finish performs the final checkpoint and stops the parent. Still checkpoints and stops the parent for a shared write Run (runId) or a legacy computerSessionId, refusing teardown when durability fails or a background process is running.",
     inputSchema: {
       runId: string2().optional().describe("an active shared write Run whose parent to checkpoint and stop, run_…"),
       computerSessionId: string2().optional().describe("legacy alternative to runId: a computerSessionId on that Computer, cms_…")
@@ -16407,7 +16425,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_…\`. 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.`;
+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 --label Fix-CI --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_… --reason Fixed-CI-and-verified-checks\`, and \`computer run receipt --run-id run_…\`. State an actual intention in --label; suspend if you need the workspace again, and finish with an accomplishments summary in --reason when done with it. Current Git-publication and safety guards still apply; push/export work that needs independent durability. 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.24.4",
+  "version": "0.24.7",
   "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",