@lambdacurry/arbor 0.23.33 → 0.23.36

package/dist/arbor.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@lambdacurry/arbor",
-  version: "0.23.33",
+  version: "0.23.36",
   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",
@@ -6908,6 +6908,11 @@ var computerRuns = sqliteTable("computer_runs", {
   f1Authority: text("f1_authority", { mode: "json" }).$type(),
   workspaceState: text("workspace_state", { mode: "json" }).$type(),
   finishRequest: text("finish_request", { mode: "json" }).$type(),
+  retentionPolicy: text("retention_policy").$type().notNull().default("none"),
+  retentionDeadlineAt: ts("retention_deadline_at"),
+  retentionMeaningfulUseAt: ts("retention_meaningful_use_at"),
+  retentionKeep: integer2("retention_keep", { mode: "boolean" }).notNull().default(false),
+  retentionRevision: integer2("retention_revision").notNull().default(0),
   status: text("status").$type().notNull().default("active"),
   label: text("label"),
   reason: text("reason"),
@@ -6918,7 +6923,8 @@ var computerRuns = sqliteTable("computer_runs", {
   threadIdx: index("computer_runs_thread_idx").on(t.threadId, t.startedAt),
   sessionIdx: index("computer_runs_session_idx").on(t.computerSessionId, t.startedAt),
   statusIdx: index("computer_runs_status_idx").on(t.computerId, t.status),
-  runtimeIdx: index("computer_runs_runtime_idx").on(t.computerId, t.runtimeState)
+  runtimeIdx: index("computer_runs_runtime_idx").on(t.computerId, t.runtimeState),
+  retentionDueIdx: index("computer_runs_retention_due_idx").on(t.retentionPolicy, t.status, t.retentionDeadlineAt)
 }));
 var packageCacheObjects = sqliteTable("package_cache_objects", {
   key: text("key").primaryKey(),
@@ -7893,6 +7899,8 @@ var events = sqliteTable("events", {
   createdAt: ts("created_at").notNull()
 }, (t) => ({
   objectIdx: index("events_object_idx").on(t.objectType, t.objectId, t.createdAt),
+  retentionMutationIdx: index("events_retention_mutation_idx").on(t.objectType, t.objectId, t.type, sql`trim(json_extract(${t.payload}, '$.mutationId'))`).where(sql`json_valid(${t.payload})`),
+  retentionProcessIdx: index("events_retention_process_idx").on(t.objectType, t.objectId, t.type, sql`trim(json_extract(${t.payload}, '$.processId'))`).where(sql`json_valid(${t.payload})`),
   createdIdx: index("events_created_idx").on(t.createdAt)
 }));
 var notifications = sqliteTable("notifications", {
@@ -8175,6 +8183,9 @@ var MAX_WAY_LEN = WAYS_TO_HELP_LIMITS.maxItemLength;
 // ../core/src/ops/computer-output.ts
 var COMPUTER_OUTPUT_DEFAULT_STALE_MS = 24 * 60 * 60 * 1000;
 
+// ../core/src/ops/computer-run-retention.ts
+var COMPUTER_RUN_RETENTION_WARNING_MS = 24 * 60 * 60 * 1000;
+
 // ../core/src/ops/computer-run.ts
 var COMPUTER_RUN_START_CHECKPOINT_RESERVATION_STALE_MS = 12 * 60 * 1000;
 var COMPUTER_RUN_F1_FINAL_FAILURE_CODES = new Set([
@@ -10053,6 +10064,39 @@ var MCP_OUTPUT_SCHEMAS = {
       })
     ])
   }),
+  computer_run_retention: looseObject({
+    runId: id,
+    destructiveExpiration: literal("disabled"),
+    report: looseObject({
+      policy: _enum(["none", "isolated-run-14d"]),
+      deadlineAt: timestamp.nullable(),
+      meaningfulUseAt: timestamp.nullable(),
+      keep: boolean2(),
+      revision: number2().int().min(0),
+      warningDelivery: literal("advisory-only"),
+      destructiveExpiration: literal("disabled"),
+      decision: _enum(["excluded", "not-due", "kept", "deferred", "eligible"]),
+      reasonCode: string2(),
+      warningDue: boolean2(),
+      warningLossScope: string2(),
+      warningAction: literal("computer_run_keep")
+    })
+  }),
+  computer_run_keep: looseObject({
+    runId: id,
+    keep: boolean2(),
+    revision: number2().int().min(0),
+    replayed: boolean2(),
+    retention: looseObject({
+      policy: _enum(["none", "isolated-run-14d"]),
+      deadlineAt: timestamp.nullable(),
+      meaningfulUseAt: timestamp.nullable(),
+      keep: boolean2(),
+      revision: number2().int().min(0),
+      warningDelivery: literal("advisory-only"),
+      destructiveExpiration: literal("disabled")
+    })
+  }),
   computer_runs: looseObject({
     computerId: id,
     threadId: id,
@@ -10728,6 +10772,8 @@ var MCP_TOOL_ANNOTATIONS = {
   computer_repo_work_status: readOnly,
   computer_run_finish: idempotent,
   computer_run_receipt: readOnly,
+  computer_run_retention: readOnly,
+  computer_run_keep: idempotent,
   computer_runs: readOnly,
   computer_exec: destructiveOpenWorld,
   computer_run_setup: destructiveIdempotentOpenWorld,
@@ -11058,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);
@@ -11086,8 +11132,8 @@ 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. 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. A local commit or Preview is not Git publication; push Git work or publish/export a needed artifact outside the Computer, then call computer_run_finish when done. Suspend for an external wait. 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.",
@@ -11860,9 +11906,10 @@ 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. 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(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.",
     inputSchema: {
       threadId: string2().describe("the Arbor Thread whose stable computer to open, thr_…"),
+      runId: string2().optional().describe("optional owned active Run; successful open renews its retention deadline"),
       idempotencyKey: string2().trim().min(1).max(200).optional().describe("optional explicit key for ONE distinct logical open; omission reuses the durable profile/Thread/recipe identity; changed options require a distinct intent; retry unchanged after response loss and never mint a new key to bypass unresolved work"),
       vcpus: number2().int().min(1).max(4).optional().describe("optional container vCPU request"),
       label: string2().optional().describe("short runtime label for operator diagnostics")
@@ -11887,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_…"),
@@ -11907,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: isolated Runs publish their exact workspace and release the Sandbox; shared Runs checkpoint the parent, and same runId resumes. Preserves unread terminal output internally for 30 days; no caller drain is required, and active/unknown work or failed preservation blocks release without replay; save needed work outside the temporary Computer first.",
     inputSchema: {
       runId: string2().describe("the active WRITE Run to suspend, run_…")
     },
@@ -11929,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 pushing Git or publishing/exporting artifacts outside this Computer; unread output lasts 30 days. An isolated Run may return status active with finishRequest pending while its owner proves Git durability, quiescence, checkpoint, and release without caller cleanup; send once, read the receipt, and use discard=true with failed or cancelled only to abandon Git after provider quiescence.",
     inputSchema: {
       runId: string2().describe("the runId returned by computer_run_start, run_…"),
       outcome: _enum(["finished", "failed", "cancelled"]).optional().describe("terminal outcome; defaults to finished"),
@@ -11943,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")
@@ -11952,6 +11999,30 @@ var ACTION_DEFINITIONS = [
     toolset: "loop",
     run: forward("computer_runtime.run_receipt")
   },
+  {
+    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.",
+    inputSchema: {
+      runId: string2().describe("the Run to inspect, run_…")
+    },
+    surfaces: ["computer-mcp", "computer-cli"],
+    toolset: "loop",
+    run: forward("computer_runtime.run_retention")
+  },
+  {
+    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.",
+    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"),
+      expectedRevision: number2().int().nonnegative().optional().describe("optional retention revision read from computer_run_receipt")
+    },
+    surfaces: ["computer-mcp", "computer-cli"],
+    toolset: "loop",
+    run: forward("computer_runtime.run_keep")
+  },
   {
     name: "computer_run_setup",
     title: "Run the declared setup",
@@ -11983,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"),
@@ -12033,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_…")
@@ -15664,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.33",
+  "version": "0.23.36",
   "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",