@lambdacurry/arbor 0.22.0 → 0.22.1

package/dist/arbor.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@lambdacurry/arbor",
-  version: "0.22.0",
+  version: "0.22.1",
   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",
@@ -9429,14 +9429,14 @@ Arbor Computer is the complete software execution platform attached to Arbor's d
 
 ${ARBOR_FEEDBACK_GUIDANCE}
 
-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_repositories then github_connect_repository 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. attach_computer mints durable protocol identity without starting a runtime; computer_open attaches as needed and starts or resumes the project environment. 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.
-2. READ THE CAPABILITIES CARD, NOT THE BACKEND. computer_open and computer_status describe the live PARENT Thread Computer and return the exact computerSessionId for parent filesystem, command, checkpoint, Preview, bundle, and stop operations. computer_status does not establish isolated Run activity; 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.
+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_repositories then github_connect_repository 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; computer_open and attach_computer are deprecated aliases (AD-306). 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.
+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.
 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 and computer_process_terminate settle a provider-absent current-generation process from exact evidence; computer_run_suspend performs that 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 and prove it with computer_repo_work_status before computer_run_finish destroys the final placement. discard=true with outcome failed or cancelled is the explicit choice to abandon unknown or proven non-durable work without replaying it.
-4. CHECKPOINT COMPLETE PARENT UNITS. computer_checkpoint advances immutable parent lineage after an intermediate complete unit; computer_stop performs the final checkpoint before teardown. An isolated Run Preview is durable review output, not adoption or a checkpoint. The internal provider-handle publication operations are not agent tools.
+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) makes the final one; finishing the last active shared Run also stops the parent. computer_checkpoint and computer_stop are deprecated aliases. An isolated Run Preview is durable review output, not adoption or a checkpoint. The internal provider-handle publication operations are not agent tools.
 5. GIT AND GITHUB ARE ORDINARY COMMANDS AFTER AUTHORIZATION. Clone, fetch, pull, push, and gh run through computer_exec using a connected human's just-in-time ambient GitHub identity. Credentials never enter argv, workspace files, Git config, checkpoints, Events, logs, or receipts. A restored Computer deliberately keeps the checkout age of its snapshot, so fetch/pull before trusting remote state.
 6. VERIFY, PREVIEW, AND EXPORT. computer_verify captures a public URL directly without opening a project runtime. computer_publish_preview preserves immutable static output from either the parent or an active isolated write Run. computer_export moves bounded files into durable Thread Attachments; for a computer:// file Artifact asleep face, export the exact locator path .tldr and a same-Thread PNG, then use artifact set_snapshot. computer_export itself does not call set_snapshot; place returned Markdown exactly where the media belongs and cite the matching attachment ids.
-7. PACKAGE, DEPLOY, ACTIVATE, AND OPERATE APPS HERE. computer_publish_app_bundle creates the immutable executable bundle from verified parent bytes. For short-lived public Artifact experiments use preview_app_create/get/retire; for published Space Apps use app_create, app_config_apply, app_deploy, app_deployment_get, app_activate, app_get, app_fetch/app_request, app_rollback, app_set_access, app_reset_state/app_restore_state, and app_archive as one workflow-closed release surface. First-class Organization/Profile Secrets remain on Arbor's collaboration MCP because they are broader identity-owned resources; App configuration here references existing Secret ids and never accepts or returns secret material.
-8. FINISH WHAT YOU START. Stop the parent after its final complete unit, finish every Run, and preserve evidence before teardown. When reporting collaboration conclusions through Arbor, pass the producing computerSessionId and attachmentIds to contribute or respond.
+7. PACKAGE, DEPLOY, ACTIVATE, AND OPERATE APPS HERE. computer_publish_app_bundle creates the immutable executable bundle from verified parent bytes through a shared write Run: push isolated work, computer_run_start with execution shared, pull, then publish. For short-lived public Artifact experiments use preview_app_create/get/retire; for published Space Apps use app_create, app_config_apply, app_deploy, app_deployment_get, app_activate, app_get, app_fetch/app_request, app_rollback, app_set_access, app_reset_state/app_restore_state, and app_archive as one workflow-closed release surface. First-class Organization/Profile Secrets remain on Arbor's collaboration MCP because they are broader identity-owned resources; App configuration here references existing Secret ids and never accepts or returns secret material.
+8. FINISH WHAT YOU START. Finish every Run — the last active shared Run's finish stops the parent — and preserve evidence before teardown. When reporting collaboration conclusions through Arbor, pass the producing computerSessionId and attachmentIds to contribute or respond.
 9. CLOSE OUT ARBOR DOGFOOD. When developing Arbor through Arbor, ask: “Did Arbor itself create meaningful friction or require an Arbor-specific workaround?” If yes, apply the classifier above and file one bounded report before closing the development loop; keep unrelated product friction out of the implementation Thread. If no, close normally without manufacturing feedback.`;
 var PROSE_LISTS = registry();
 function proseList(description) {
@@ -10128,7 +10128,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "attach_computer",
     title: "Attach a Thread computer",
-    description: "Create or reuse a Thread's stable Computer identity and mint an immutable collaborator receipt without starting provider runtime. Normally computer_open performs this attachment as part of opening; use this tool only when durable protocol identity is needed separately.",
+    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.",
     inputSchema: {
       threadId: string2().describe("the Thread whose computer you are attaching, thr_…")
     },
@@ -10139,7 +10139,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_open",
     title: "Open a Thread computer",
-    description: "Open a usable Thread workspace with verified root repository instruction pointers; omit the key to retry the same logical open, with unsafe recovery refused. A successful open means the first allowed exec can proceed: Compatible execution is selected internally, additive authorized repository drift auto-reconciles, 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. 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_…"),
       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"),
@@ -10186,7 +10186,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_suspend",
     title: "Suspend a run",
-    description: "Checkpoint an active isolated WRITE Run's exact workspace, publish that restore point, and release its Sandbox during an external wait; the same runId resumes on the next operation. Performs bounded process read/terminate/settlement internally: suspends when settled, returns retryable busy if a process is active, or fail-closes on unknown mutation and never replays unknown work.",
+    description: "Checkpoint an active WRITE Run for an external wait (the same runId resumes next): an isolated Run publishes its exact workspace and releases its Sandbox, a shared Run checkpoints the parent lineage. Performs bounded process read/terminate/settlement internally: suspends when settled, returns retryable busy if a process is active, or fail-closes on unknown mutation and never replays unknown work.",
     inputSchema: {
       runId: string2().describe("the active isolated WRITE Run to suspend, run_…")
     },
@@ -10208,7 +10208,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_finish",
     title: "Finish a run",
-    description: "Finish a Run with an explicit terminal outcome; ordinary finish refuses unsettled operations and proven non-durable isolated WRITE work. To abandon an unknown or non-durable disposable Run without replaying it, pass discard=true with outcome failed or cancelled; the receipt preserves unknown operation and durability evidence, and repeating the same outcome is a safe no-op.",
+    description: "Finish a Run with an explicit terminal outcome; ordinary finish refuses unsettled operations and proven non-durable isolated WRITE work, and the last shared Run's finish also stops the parent. To abandon an unknown or non-durable disposable Run without replaying it, pass discard=true with outcome failed or cancelled; the receipt keeps the evidence and repeating the outcome is a safe no-op.",
     inputSchema: {
       runId: string2().describe("the runId returned by computer_run_start, run_…"),
       outcome: _enum(["finished", "failed", "cancelled"]).optional().describe("terminal outcome; defaults to finished"),
@@ -10233,9 +10233,10 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_runs",
     title: "List runs",
-    description: "List active or recent Runs for this Thread Computer when deciding whether to resume existing work or start another unit. Returns each Run's mode, execution placement, workspace identity, and lifecycle status.",
+    description: "List active or recent Runs on the Computer that owns runId when deciding whether to resume existing work or start another unit. Returns each Run's mode, execution placement, workspace identity, and lifecycle status.",
     inputSchema: {
-      computerSessionId: string2().describe("the computerSessionId returned by computer_open, cms_…"),
+      runId: string2().optional().describe("any Run on the Computer to list, run_…"),
+      computerSessionId: string2().optional().describe("legacy alternative to runId: a computerSessionId on that Computer, cms_…"),
       status: _enum(["active", "finished", "failed", "cancelled"]).optional().describe("filter to one lifecycle status"),
       limit: number2().int().min(1).max(100).optional().describe("rows to return (default 20)")
     },
@@ -10246,9 +10247,9 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_exec",
     title: "Run a command",
-    description: "Run one bounded shell operation in a parent Computer or Run with ambient GitHub authorization for connected humans. A long command returns processId if still running — poll computer_process_read (background:true skips the wait; timeout kills the process); after a missed isolated response use computer_run_receipt.operations[].operationId with computer_process_read instead of repeating the mutation.",
+    description: "Run one bounded shell operation in a Run (pass runId) with ambient GitHub authorization for connected humans. A long command returns processId if still running — poll computer_process_read (background:true skips the wait; timeout kills the process); after a missed isolated response use computer_run_receipt.operations[].operationId with computer_process_read instead of repeating the mutation.",
     inputSchema: {
-      computerSessionId: string2().optional().describe("the computerSessionId returned by computer_open, cms_…; required unless runId is supplied"),
+      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"),
@@ -10267,7 +10268,7 @@ var ACTION_DEFINITIONS = [
     title: "Read a background process",
     description: "Read one provider-owned process from computer_exec, including a recovered Run operation, using nextCursor for incremental output. Successful Run reads durably retain the latest provider observation; a later timeout stays unknown and unsafe while returning it with age, and Arbor settles the durable operation only from terminal or exact provider-absence proof.",
     inputSchema: {
-      computerSessionId: string2().optional().describe("the computerSessionId returned by computer_open, cms_…; required unless runId is supplied"),
+      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 process read; omit for a small latest tail"),
@@ -10282,7 +10283,7 @@ var ACTION_DEFINITIONS = [
     title: "Terminate a background process",
     description: "Terminate a background process started by computer_exec when it should no longer run, stopping the provider-owned process tree without shell PIDs or ps/kill. Repeating terminate for an already-absent or already-complete process is a no-op that settles that exact durable operation from the available evidence.",
     inputSchema: {
-      computerSessionId: string2().optional().describe("the computerSessionId returned by computer_open, cms_…; required unless runId is supplied"),
+      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 opaque processId returned by computer_exec(background=true), proc_…")
     },
@@ -10293,9 +10294,10 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_status",
     title: "Inspect a computer",
-    description: "Inspect the live PARENT Thread Computer's capabilities, live can-I-exec readiness, processes, and profile. Transient session unavailability drops command capabilities and may retry computer_open once; a terminal unknown mutation is a non-retryable stop — this does not report isolated Run command state, so use computer_run_receipt for Run state or get_computer for restore-safety.",
+    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.",
     inputSchema: {
-      computerSessionId: string2().describe("the computerSessionId returned by computer_open, cms_…")
+      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_…")
     },
     surfaces: ["computer-mcp", "computer-cli"],
     toolset: "loop",
@@ -10388,7 +10390,7 @@ var ACTION_DEFINITIONS = [
     title: "Export a Thread file",
     description: "Export one bounded file from the parent Computer or a Run as a durable Thread Attachment, with ready-to-place attachments[].markdown to put exactly where the media belongs and a downloadUrl you can GET with your own Arbor credential to see it yourself. For a Layer 1 snapshot, export the computer:// .tldr locator path and a same-Thread PNG, then use artifact set_snapshot; this never mints.",
     inputSchema: {
-      computerSessionId: string2().optional().describe("the computerSessionId returned by computer_open, cms_…; required unless runId is supplied"),
+      computerSessionId: string2().optional().describe("legacy alternative to runId: a computerSessionId on that Computer, cms_…; required unless runId is supplied"),
       runId: string2().optional().describe("route this export according to this Run execution placement, run_…"),
       path: string2().describe("absolute path to one supported file under /workspace"),
       description: string2().min(1).max(500).describe("concise description of what the file shows or contains; becomes image alt text, a video caption, and the Artifact summary"),
@@ -10403,7 +10405,7 @@ var ACTION_DEFINITIONS = [
     title: "Write a project file",
     description: "Write or replace one file in the parent Computer or a Run when the Computer surface is your filesystem editing path. Routes by runId when supplied and supports UTF-8 or explicit base64 bytes.",
     inputSchema: {
-      computerSessionId: string2().optional().describe("the computerSessionId returned by computer_open, cms_…; required unless runId is supplied"),
+      computerSessionId: string2().optional().describe("legacy alternative to runId: a computerSessionId on that Computer, cms_…; required unless runId is supplied"),
       path: string2().describe("absolute path under /workspace, or a path inside the run"),
       runId: string2().optional().describe("route this write according to this Run execution placement, run_… (from computer_run_start)"),
       content: string2().describe("complete UTF-8 content, or base64 bytes when encoding=base64"),
@@ -10416,9 +10418,10 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_checkpoint",
     title: "Checkpoint completed work",
-    description: "Checkpoint a completed unit from the live parent Thread Computer into durable Thread lineage when more parent work will follow. It is not Run-scoped; isolated Run work must be made durable through its repository workflow, and running background processes can block the checkpoint.",
+    description: "Deprecated by AD-306: computer_run_suspend(runId) checkpoints a shared write Run's parent lineage and computer_run_finish makes the final one. Still checkpoints the live parent for a shared write Run (runId) or a legacy computerSessionId; isolated Runs are refused, and a running background process can block it.",
     inputSchema: {
-      computerSessionId: string2().describe("the computerSessionId returned by computer_open, cms_…")
+      runId: string2().optional().describe("an active shared write Run whose parent lineage to checkpoint, run_…"),
+      computerSessionId: string2().optional().describe("legacy alternative to runId: a computerSessionId on that Computer, cms_…")
     },
     surfaces: ["computer-mcp", "computer-cli"],
     toolset: "loop",
@@ -10429,7 +10432,7 @@ var ACTION_DEFINITIONS = [
     title: "Publish an immutable static Preview",
     description: "Publish one checked HTML file or bounded static directory as a private immutable Preview for review. Parent publication checkpoints first; isolated Run publication freezes that Run's bytes without adopting it, and the returned arborthreads.dev URL survives teardown.",
     inputSchema: {
-      computerSessionId: string2().optional().describe("the computerSessionId returned by computer_open, cms_…; required for parent publication, optional when runId is supplied"),
+      computerSessionId: string2().optional().describe("legacy alternative to runId: a computerSessionId on that Computer, cms_…; required for parent publication, optional when runId is supplied"),
       runId: string2().optional().describe("active isolated write Run whose static workspace bytes should be published as review output"),
       path: string2().describe("absolute path to one HTML file or static build directory under /workspace"),
       title: string2().min(1).max(160).describe("short factual Preview title"),
@@ -10442,9 +10445,10 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_publish_app_bundle",
     title: "Publish an immutable AppBundle",
-    description: "Publish a content-addressed AppBundle from the live parent Computer after a green build when an ArtifactVersion is ready for app deployment; Arbor selects or acquires compatible bun-typescript-v1 execution internally. Verifies entry bytes against the ArtifactVersion, captures source/Git provenance and static assets, and returns bundleId; isolated Runs are not accepted.",
+    description: "Publish an immutable AppBundle from the parent Computer behind a shared write Run (runId) after a green build when an ArtifactVersion is ready; Arbor acquires compatible bun-typescript-v1 execution internally. Verifies entry bytes against the ArtifactVersion, captures source/Git provenance and static assets, and returns bundleId; isolated Runs are refused, so push and start a shared Run first.",
     inputSchema: {
-      computerSessionId: string2().describe("the computerSessionId returned by computer_open, cms_…"),
+      runId: string2().optional().describe("an active shared write Run on the parent whose bytes to publish, run_…"),
+      computerSessionId: string2().optional().describe("legacy alternative to runId: a computerSessionId on that Computer, cms_…"),
       artifactVersionId: string2().describe("the source ArtifactVersion, artv_…"),
       entryPath: string2().describe("absolute TypeScript/JavaScript Worker entry under /workspace"),
       assetsPath: string2().optional().describe("optional absolute static-asset directory under /workspace"),
@@ -10480,9 +10484,10 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_stop",
     title: "Checkpoint and stop",
-    description: "Checkpoint and stop an opened parent Computer after the final unit of work. Teardown is refused if checkpoint durability fails or a background process is still running, so state is not silently discarded.",
+    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.",
     inputSchema: {
-      computerSessionId: string2().describe("the computerSessionId returned by computer_open, cms_…")
+      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_…")
     },
     surfaces: ["computer-mcp", "computer-cli"],
     toolset: "loop",

package/package.json

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