@lambdacurry/arbor 0.22.30 → 0.22.31

package/dist/arbor.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@lambdacurry/arbor",
-  version: "0.22.30",
+  version: "0.22.31",
   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",
@@ -10130,7 +10130,7 @@ Arbor's MCP is the collaboration and durable-knowledge surface. Configure, autho
 
 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.`;
 var ARBOR_SKILL_MARKDOWN = renderArborSkill(ORIENTATION);
-var COMPUTER_ORIENTATION = `Long Computer work returns a processId handle — do not hold one tool call for a full test or build. \`computer_exec\` runs a command; if the result is still running, observe it with \`computer_process_read\`; read a truncated continuation only when you need more output. Finish and suspend preserve unread terminal output internally, with original process IDs/cursors recoverable for 30 days. Do not chain \`pnpm test && pnpm build\` in one exec; split steps or pass \`background:true\`. The CLI polls only while the process is silent unless \`--no-wait\`; it returns the first bounded output page instead of concatenating continuation pages into one agent context.
+var COMPUTER_ORIENTATION = `Long Computer work returns a processId handle — do not hold one tool call for a full test or build. \`computer_exec\` runs a command; if the result is still running, observe it with \`computer_process_read\`; read a truncated continuation only when you need more output. Finish and suspend preserve unread terminal output internally, with original process IDs/cursors recoverable for 30 days. Do not chain \`pnpm test && pnpm build\` in one exec; split steps or pass \`background:true\`. An explicit waitForTerminalMs uses one server wait and canonical output page; otherwise the CLI polls only while the process is silent unless \`--no-wait\`. It never concatenates continuation pages into one agent context.
 
 Arbor Computer is the complete software execution platform attached to Arbor's durable collaboration graph. It configures project environments, executes and verifies work, packages and releases Apps, and preserves reviewable evidence; it does not schedule agents or replace Arbor collaboration.
 
@@ -10954,16 +10954,17 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_exec",
     title: "Run a command",
-    description: "Run a shell command in runId with ambient GitHub authorization and /workspace/.local/bin on PATH; timeout kills the process. Observe running work with computer_process_read, use nextCursor for a truncated output page when needed, and finish without draining; after a missed response use computer_run_receipt.operations[].operationId with computer_process_read instead of repeating the mutation.",
+    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.",
     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"),
       runId: string2().optional().describe("route this command according to this Run execution placement, run_… (from computer_run_start)"),
       cwd: string2().optional().describe("working directory under /workspace, or under the run; omit to use defaultCwd"),
       timeout: number2().int().min(1000).max(1800000).optional().describe("process kill deadline in milliseconds, from 1,000 through 1,800,000 — not the RPC hold"),
-      background: boolean2().optional().describe("start the process and return immediately without the short RPC wait"),
-      activityLabel: string2().min(1).max(COMPUTER_RUN_ACTIVITY_LABEL_MAX).optional().describe("short human-readable label for run-scoped background work; Arbor records this label instead of the raw command or output"),
-      activityKind: literal("verification").optional().describe("mark a labeled run-scoped background command as a verification check; its provider-observed terminal result is recorded as verification.finished"),
+      background: boolean2().optional().describe("start the process and return immediately without the short RPC wait; mutually exclusive with waitForTerminalMs"),
+      waitForTerminalMs: number2().int().min(0).max(45000).optional().describe("explicit terminal-observation window from 0 through 45,000 milliseconds; 0 returns immediately, a positive value returns one canonical output page when the native wait ends or expires, and descendants may keep the result running; mutually exclusive with background"),
+      activityLabel: string2().min(1).max(COMPUTER_RUN_ACTIVITY_LABEL_MAX).optional().describe("short human-readable label for retained run-scoped work selected by background or waitForTerminalMs; Arbor records this label instead of the raw command or output"),
+      activityKind: literal("verification").optional().describe("mark labeled retained run-scoped work as a verification check; its provider-observed terminal result is recorded as verification.finished"),
       strict: boolean2().optional().describe("fail on the first unhandled command or pipeline failure; defaults to true, set false only for intentional best-effort execution")
     },
     surfaces: ["computer-mcp", "computer-cli"],
@@ -10973,13 +10974,14 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_process_read",
     title: "Read a background process",
-    description: "Read original process output using nextCursor; preserved output stays readable for 30 days after preservation, including repeated cursors after finish/suspend, without provider wake. Live reads retain the latest observation; a later timeout remains unknown/unsafe with its age, and Arbor settles the durable operation only from terminal or exact provider-absence proof.",
+    description: "Read process output with nextCursor; preserved bytes remain available for 30 days after preservation, including repeated cursors after finish/suspend, without provider wake. waitForTerminalMs adds one bounded native observation and page; expiry or descendants may still run, transport failure stays unknown/unsafe, and Arbor settles the durable operation only from terminal or exact absence proof.",
     inputSchema: {
       computerSessionId: string2().optional().describe("legacy alternative to runId: a computerSessionId on that Computer, cms_…; required unless runId is supplied"),
       runId: string2().optional().describe("the Run that owns this process, if it was started inside a Run"),
       processId: string2().min(1).describe("the processId returned by background exec, or matching computer_run_receipt.operations[].operationId for recovered foreground Run work, proc_…"),
       cursor: string2().optional().describe("continue after nextCursor from the prior result; omit to read from the beginning"),
-      maxBytes: number2().int().min(1024).max(65536).optional().describe("maximum combined output bytes to return; default 4,096, opt up only when needed")
+      maxBytes: number2().int().min(1024).max(65536).optional().describe("maximum combined output bytes to return; default 4,096, opt up only when needed"),
+      waitForTerminalMs: number2().int().min(0).max(45000).optional().describe("use one native terminal-observation window up to this many milliseconds, then return one canonical output page; 0 is immediate, surviving descendants may remain running, and omission preserves the current read behavior")
     },
     surfaces: ["computer-mcp", "computer-cli"],
     toolset: "loop",
@@ -14149,7 +14151,7 @@ Alias: \`arbor ${aliases[0]}\` (the tool-name form) resolves to this same comman
 Aliases: ${aliases.map((alias) => `\`arbor ${alias}\``).join(", ")} (tool-name forms) resolve to this same command.` : "";
   const heading = `${commandWords(action)}${aliases.length === 1 ? ` (alias: ${aliases[0]})` : aliases.length > 1 ? ` (aliases: ${aliases.join(", ")})` : ""}`;
   const waitLines = action.name === "computer_exec" ? [
-    "  --no-wait [<boolean>]  [optional] — return a running processId immediately instead of polling computer_process_read"
+    "  --no-wait [<boolean>]  [optional] — return a running processId immediately instead of polling computer_process_read; mutually exclusive with --wait-for-terminal-ms"
   ] : [];
   return `${heading} — ${action.description}
 
@@ -14178,7 +14180,7 @@ function commandCatalog() {
           kind: "boolean",
           required: false,
           acceptsFile: false,
-          description: "return a running processId immediately instead of polling computer_process_read"
+          description: "return a running processId immediately instead of polling computer_process_read; mutually exclusive with --wait-for-terminal-ms"
         }
       ] : []
     ]
@@ -14240,6 +14242,12 @@ async function runObjectVerb(positionals, flags, ctx) {
     delete inputFlags.json;
   }
   const input = buildInput(action.inputSchema, inputFlags, commandWords(action));
+  if (action.name === "computer_exec" && flags["no-wait"] !== undefined && input.waitForTerminalMs !== undefined) {
+    throw new UsageError("--no-wait and --wait-for-terminal-ms are mutually exclusive", {
+      reason: "validation.invalid_value",
+      field: "waitForTerminalMs"
+    });
+  }
   if (action.name === "app_request" && input.json !== undefined) {
     if (input.body !== undefined) {
       throw new UsageError("--json and --body are mutually exclusive", {
@@ -14261,7 +14269,7 @@ async function runObjectVerb(positionals, flags, ctx) {
 `, ctx);
   }
   let value = await action.run(httpExecutor, input);
-  if (action.name === "computer_exec" && !truthyFlag(flags["no-wait"])) {
+  if (action.name === "computer_exec" && !truthyFlag(flags["no-wait"]) && input.waitForTerminalMs === undefined) {
     value = await waitForComputerExec(httpExecutor, input, value, ctx);
   }
   emitData(shapeActionOutput(action.name, value, input), action.name, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambdacurry/arbor",
-  "version": "0.22.30",
+  "version": "0.22.31",
   "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",