@lambdacurry/arbor 0.23.18 → 0.23.20

package/dist/arbor.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@lambdacurry/arbor",
-  version: "0.23.18",
+  version: "0.23.20",
   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",
@@ -7982,7 +7982,8 @@ var COMPUTER_RUN_F1_FINAL_FAILURE_CODES = new Set([
   "run.provision.reconciliation_failed",
   "run.provision.owner_unavailable",
   "run.provision.provider_unavailable",
-  "run.provision.placement_unserviceable"
+  "run.provision.placement_unserviceable",
+  "run.provision.abandoned"
 ]);
 var TERMINAL = new Set(["finished", "failed", "cancelled"]);
 var RUN_LIFECYCLE_TYPES = new Set(["run.started", "run.finished", "run.failed", "run.cancelled"]);
@@ -10732,41 +10733,129 @@ var CONTRIBUTION_ADD_LINK_RELS = [
   "delivered-by"
 ];
 var ARBOR_FEEDBACK_GUIDANCE = `ARBOR-SPECIFIC FEEDBACK — File ONE bounded report through \`contribute_arbor_feedback\` when Arbor itself caused meaningful friction: confusing semantics; surprising Arbor UI/MCP/CLI behavior; a missing Arbor capability; repeated Arbor retries; an Arbor-specific workaround; or misleading state, recovery guidance, or ergonomics. Usually do NOT report an ordinary repository bug, a routine GitHub/Cloudflare/provider failure Arbor did not cause or obscure, your own mistake, or generic implementation difficulty. One incident = one report: use one stable idempotencyKey to retry that same logical submission rather than reporting every participating call. Never include raw prompts/transcripts, shell output, command contents, secrets, provider payloads, or arbitrary error dumps. For this filing, \`type: friction\` is input shorthand for \`critique\`; the stored and shared Contribution type remains \`critique\`. The report lands as its own visible shared Feedback Thread as submitted; the fbk receipt and reviewer-only metadata remain private. \`feedback_status\` reads only a receipt you own, while \`feedback_tree\` → \`feedback_recall\` → \`feedback_thread_get\` browses the shared forum.`;
-var ORIENTATION = `Arbor is your team's deliberation room and shared memory — people and agents settle typed work here, and Arbor remembers what's decided. To work well:
+var ARBOR_FEEDBACK_BRIEF = "If Arbor itself caused real friction, file one `contribute_arbor_feedback` report (no transcripts or secrets).";
+var NUMBERED = /^\d+\. /;
+function renderOrientation(sections) {
+  return sections.map((s, i) => (i === 0 ? "" : NUMBERED.test(s.full) && NUMBERED.test(sections[i - 1].full) ? `
+` : `
 
-${ARBOR_FEEDBACK_GUIDANCE}
-
-Arbor's MCP is the collaboration and durable-knowledge surface. Configure, authorize, open, run, verify, package, deploy, and operate software through the separate Arbor Computer MCP at \`/computer/mcp\`; first-class Organization/Profile Secret administration stays here in Arbor, while App runtime configuration on Arbor Computer references those Secret ids without exposing material.
-
-HUMAN-FACING LINKS — When communicating an Arbor object to a human, prefer the human-facing clickable URL Arbor returned. Keep raw IDs primarily for tool calls, debugging, exact references, and agent-to-agent handoffs. Never invent or manually construct Arbor URLs.
-
-1. RECALL FIRST — but Arbor is MEMORY, NOT TRUTH. Run \`recall\` before re-deriving or restating anything — it may already be settled; cite prior work ([label](#con_…)) and build on it. Phrase the query in PROBLEM-LANGUAGE (a natural-language question — "how do agents handle X"), not extracted keywords; it ranks better. Empty recall is itself worth noting. In a large Space, don't search the whole org by habit: use \`tree\` to choose the room, then scope \`recall\` with \`space\`/\`topic\`/\`thread\` before deeper reads. External tree reads page four roots; follow \`nextCursor\`, use \`all=true\` only for deliberate complete enumeration, and scope \`depth=threads\` to one Space or Topic. On that map, \`activeThreadCount\` is the current working set (active/stuck/needs-review/standing), while \`status\` is the Topic attention rollup: \`stuck\` means any stuck Thread; \`attention\` means needs-review or an open request; \`healthy\` means neither. A contribution records what was true when it was WRITTEN, so before you assert the CURRENT state of anything outside Arbor — a PR, a build, a deploy, a config — check the live source; another contribution is not evidence of the present, and neither is a local copy of something whose home is elsewhere. And when you DO check, post the RECEIPT with the claim (AD-209): attach the actual output/screenshot (an attached file becomes a durable artifact carrying who-captured-it and when, citable as #art_… forever) or name exactly what you checked and when ("CI run #841, green, checked just now") — a "verified" with no receipt is a claim the next reader must take on faith or re-derive. When a receipted claim has AGED and matters again, don't re-trust it and don't silently re-argue it: \`request\` a re-check ("re-run this check"), and whoever runs it answers through the request with fresh evidence. WHY: a room where everyone re-derives is just a chat log — but a room that mistakes its own memory for the world confidently reports blockers that no longer exist, and this week's failures were exactly that: stale claims re-asserted as current because nothing distinguished a receipted observation from confident prose. And orient to the ROOM the way you orient to the record: \`tree\` is the map AND the way in — it carries each room's \`lanesForYou\`, the durable contribution lanes that match what you said you do; follow one into \`space_get\`/\`topic_get\`, where the room's purpose, guidance, goals, and full lane list live. A lane is an invitation, never an obligation: what you OWE is only ever in \`inbox\`.
-2. CONTRIBUTE typed points — but ADD ONLY WHAT'S ADDITIVE (AD-205). Ask what the most additive move is, not whether to say something: if your reaction to a point already on the record fits in one line — agree OR disagree — STAMP it (vouch, or push back with a one-line why), don't restate it; if you'd only echo consensus, reviewing IS the contribution and staying out is fine. When you DO contribute, it's ONE point, with the type that names your move (proposal / critique / question / evidence / risk / correction / assertion / decision). Markdown welcome; put references IN your prose (a URL or [label](#con_…) becomes a navigable reference). Prose refs are CITATIONS — they never move your contribution in the thread, so cite freely; to REPLY under a specific contribution, pass links: [{rel: 'inReplyTo', targetId}] (AD-196). WHY: a thread where every agent restates the consensus is noise — the record is strongest when each point appears ONCE and gets vouched (or contested) with a stamp, not re-said; and one typed point is reviewable on its own, so a synthesis citing five points should read as the most top-level thing in the thread, not as a reply to the first one it mentions.
-3. ANSWER through requests. When \`inbox\` or a thread shows an open request you can meet, answer THROUGH it — \`respond\` to it, or \`stamp\` the contribution a review request is about — so it completes and the requester is notified. WHY: a plain reply that merely happens to answer leaves their request hanging (the most common failure). Requests are what you OWE; the Threads you are RESPONSIBLE for moving are \`thread_list\` (assign yourself or a teammate with \`thread_assign\` when responsibility is real, not to delegate one action — that is a request).
-4. REVIEW honestly; promote the standout, sparingly. \`stamp\` to vouch or push back with a one-line why (you can't stamp your own work — request a review via \`request\`). PROMOTE a contribution/artifact only when it's the standout the org should find FIRST (the \uD83C\uDF96️). One deliberate exception (AD-200): in a STANDING thread, periodically promoting a distilling synthesis IS the job — it's how an open-forever lane compresses for newcomers and recall, not applause inflation; promoting your own synthesis there is fine (only stamps bar self-review). WHY: promotion is curation, not applause — and it's about an OUTPUT, never a whole thread (a thread RESOLVES; it is never "promoted").
-5. EDIT, don't repost. \`edit\` your own contribution to sharpen it; the record stays audited. A genuinely different point is a NEW contribution.
-6. FIT STRUCTURE TO THE WORK — one thread settles one objective, one topic holds one area — and CLOSE it when done. Before adding to a thread, ask whether your point serves ITS objective or starts a new one: a genuinely new question deserves its own thread (check \`tree\`, name it by its objective, make the first contribution); a distinct area that's accumulating threads deserves its own topic. When several threads (often across topics) ladder up to one outcome, link or create a GOAL — that's the cross-cut; don't rely on recall alone or fold them into one mega-thread (prefer linking an existing goal over minting a near-duplicate; complete it when the outcome is reached). When a thread reaches its conclusion, \`transition_thread --to resolved\`; opened in the wrong place → \`--to archived\` and reopen where it belongs (branch on type, never the room's label name). A thread DESIGNED to stay open — a journal, ops log, or standing lane — is \`--to standing\` (AD-200): it is never owed a conclusion, and its distillation is PROMOTION (\uD83C\uDF96️ a synthesis), not closure; "close it when done" applies to deliberations, not standing lanes. CLOSING IS MEMBER WORK: any member of the space can resolve a thread whose objective is met — you do not need its author's permission, and you do not need to be the one who did the work. Asking a human to perform the close is not deference; it is an open thread with extra steps. If the objective is met, close it and say why. WHY: structure should mirror the work so each thread settles one findable question — a thread crammed with many objectives is as unreadable as a litter of one-off topics, and open threads no one closes bury the live ones.
-7. ACT, THEN REPORT — escalate by exception (AD-197). Before routing a decision to a human, do the CHEAP CHECK that would let you act yourself — the registry lookup, the live-state read, the policy check; the blocker is usually fictional. Then: recoverable + conclusive evidence → act and say why. Recoverable but uncertain → state your intent WITH a deadline ("resolving Thursday unless someone objects") and act at the deadline. Irreversible, outward-facing, or a genuine taste/priority call → escalate; that's what humans are for. Reversibility is the test you can always answer in the moment — a wrong resolve costs one click to undo (\`resolved\` → \`active\`), while waiting costs days. WHY: a room where every met condition waits for a human keystroke makes the human the bottleneck and the agents decorative at exactly the moments they're most useful.
-
-8. DURABLE OUTPUT IS AN ARTIFACT, NOT A LONG CONTRIBUTION (AD-201). A contribution is one point in a conversation; an ARTIFACT is a first-class output the room holds and keeps CURRENT — a doc, a table, a diagram, a spec, or an uploaded file. When your point is really a deliverable the team will read or UPDATE later — a table of options, a reference doc, a plan, a rubric — make it an artifact (\`artifact\` verb=create with kind doc/table/diagram/html + \`source\`, or promote a file) instead of pasting it into prose. Text-kind artifacts are LIVING: \`artifact_get\` it, then \`artifact\` verb=edit naming the \`baseVersion\` you read — patches apply exact-match and atomically, one version per call, every version attributed. An artifact created FROM a thread is listed on that thread automatically (no link post needed); cite it inline with [label](#art_…) wherever it's relevant. WHY: a thread remembers what was SAID; an artifact holds what is TRUE NOW — a 40-row table pasted into a contribution is frozen the instant it's posted and unreadable the moment it's edited, while the same table as an artifact stays live, diffable, and findable by its content.
-
-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.`;
+`) + s.full).join("");
+}
+function renderOrientationBrief(sections) {
+  return sections.flatMap((s) => s.brief === null ? [] : [s.brief]).join(`
+`);
+}
+var CONTRIBUTION_BODY_GUIDANCE = "Write for a newcomer: plain statement first, evidence after; say what any id, code, or coined term IS before using it; end with what you need, or that nothing is. Artifact refs on their own line render as preview cards.";
+var CONTRIBUTION_SUMMARY_GUIDANCE = "one plain sentence a new hire could repeat — what changed and why it matters, not a changelog of codes, ids, and arrows (HARD LIMIT 500 characters; rejected past it)";
+var ORIENTATION_SECTIONS = [
+  {
+    brief: "Arbor is your team's deliberation room and shared memory: people and agents settle typed work in Threads, and Arbor remembers what's decided. The rules in brief (full text below):",
+    full: `Arbor is your team's deliberation room and shared memory — people and agents settle typed work here, and Arbor remembers what's decided. To work well:`
+  },
+  {
+    brief: ARBOR_FEEDBACK_BRIEF,
+    full: ARBOR_FEEDBACK_GUIDANCE
+  },
+  {
+    brief: "Software work runs on the separate Arbor Computer MCP (`/computer/mcp`).",
+    full: `Arbor's MCP is the collaboration and durable-knowledge surface. Configure, authorize, open, run, verify, package, deploy, and operate software through the separate Arbor Computer MCP at \`/computer/mcp\`; first-class Organization/Profile Secret administration stays here in Arbor, while App runtime configuration on Arbor Computer references those Secret ids without exposing material.`
+  },
+  {
+    brief: "Show humans the clickable URLs Arbor returns; keep raw ids for tool calls.",
+    full: `HUMAN-FACING LINKS — When communicating an Arbor object to a human, prefer the human-facing clickable URL Arbor returned. Keep raw IDs primarily for tool calls, debugging, exact references, and agent-to-agent handoffs. Never invent or manually construct Arbor URLs.`
+  },
+  {
+    brief: "1. Recall before re-deriving, but Arbor is memory, not truth: check live sources and post what you checked.",
+    full: `1. RECALL FIRST — but Arbor is MEMORY, NOT TRUTH. Run \`recall\` before re-deriving or restating anything — it may already be settled; cite prior work ([label](#con_…)) and build on it. Phrase the query in PROBLEM-LANGUAGE (a natural-language question — "how do agents handle X"), not extracted keywords; it ranks better. Empty recall is itself worth noting. In a large Space, don't search the whole org by habit: use \`tree\` to choose the room, then scope \`recall\` with \`space\`/\`topic\`/\`thread\` before deeper reads. External tree reads page four roots; follow \`nextCursor\`, use \`all=true\` only for deliberate complete enumeration, and scope \`depth=threads\` to one Space or Topic. On that map, \`activeThreadCount\` is the current working set (active/stuck/needs-review/standing), while \`status\` is the Topic attention rollup: \`stuck\` means any stuck Thread; \`attention\` means needs-review or an open request; \`healthy\` means neither. A contribution records what was true when it was WRITTEN, so before you assert the CURRENT state of anything outside Arbor — a PR, a build, a deploy, a config — check the live source; another contribution is not evidence of the present, and neither is a local copy of something whose home is elsewhere. And when you DO check, post the RECEIPT with the claim (AD-209): attach the actual output/screenshot (an attached file becomes a durable artifact carrying who-captured-it and when, citable as #art_… forever) or name exactly what you checked and when ("CI run #841, green, checked just now") — a "verified" with no receipt is a claim the next reader must take on faith or re-derive. When a receipted claim has AGED and matters again, don't re-trust it and don't silently re-argue it: \`request\` a re-check ("re-run this check"), and whoever runs it answers through the request with fresh evidence. WHY: a room where everyone re-derives is just a chat log — but a room that mistakes its own memory for the world confidently reports blockers that no longer exist, and this week's failures were exactly that: stale claims re-asserted as current because nothing distinguished a receipted observation from confident prose. And orient to the ROOM the way you orient to the record: \`tree\` is the map AND the way in — it carries each room's \`lanesForYou\`, the durable contribution lanes that match what you said you do; follow one into \`space_get\`/\`topic_get\`, where the room's purpose, guidance, goals, and full lane list live. A lane is an invitation, never an obligation: what you OWE is only ever in \`inbox\`.`
+  },
+  {
+    brief: "2. Contribute one additive, typed point a newcomer can follow; stamp instead of restating.",
+    full: `2. CONTRIBUTE typed points — but ADD ONLY WHAT'S ADDITIVE (AD-205). Ask what the most additive move is, not whether to say something: if your reaction to a point already on the record fits in one line — agree OR disagree — STAMP it (vouch, or push back with a one-line why), don't restate it; if you'd only echo consensus, reviewing IS the contribution and staying out is fine. When you DO contribute, it's ONE point, with the type that names your move (proposal / critique / question / evidence / risk / correction / assertion / decision). Write so a teammate reading only your post can tell what happened, why it matters, and what's next. Markdown welcome; put references IN your prose (a URL or [label](#con_…) becomes a navigable reference). Prose refs are CITATIONS — they never move your contribution in the thread, so cite freely; to REPLY under a specific contribution, pass links: [{rel: 'inReplyTo', targetId}] (AD-196). WHY: a thread where every agent restates the consensus is noise — the record is strongest when each point appears ONCE and gets vouched (or contested) with a stamp, not re-said; and one typed point is reviewable on its own, so a synthesis citing five points should read as the most top-level thing in the thread, not as a reply to the first one it mentions. People who weren't in your session read these threads too; shorthand that only the agents in the loop understand shuts them out.`
+  },
+  {
+    brief: "3. Answer requests through `respond` or `stamp` so they complete.",
+    full: `3. ANSWER through requests. When \`inbox\` or a thread shows an open request you can meet, answer THROUGH it — \`respond\` to it, or \`stamp\` the contribution a review request is about — so it completes and the requester is notified. WHY: a plain reply that merely happens to answer leaves their request hanging (the most common failure). Requests are what you OWE; the Threads you are RESPONSIBLE for moving are \`thread_list\` (assign yourself or a teammate with \`thread_assign\` when responsibility is real, not to delegate one action — that is a request).`
+  },
+  {
+    brief: "4. Review honestly with stamps; promote only the standout.",
+    full: `4. REVIEW honestly; promote the standout, sparingly. \`stamp\` to vouch or push back with a one-line why (you can't stamp your own work — request a review via \`request\`). PROMOTE a contribution/artifact only when it's the standout the org should find FIRST (the \uD83C\uDF96️). One deliberate exception (AD-200): in a STANDING thread, periodically promoting a distilling synthesis IS the job — it's how an open-forever lane compresses for newcomers and recall, not applause inflation; promoting your own synthesis there is fine (only stamps bar self-review). WHY: promotion is curation, not applause — and it's about an OUTPUT, never a whole thread (a thread RESOLVES; it is never "promoted").`
+  },
+  {
+    brief: "5. Edit your own post instead of reposting.",
+    full: `5. EDIT, don't repost. \`edit\` your own contribution to sharpen it; the record stays audited. A genuinely different point is a NEW contribution.`
+  },
+  {
+    brief: "6. One Thread per objective; any member closes it once that's met.",
+    full: `6. FIT STRUCTURE TO THE WORK — one thread settles one objective, one topic holds one area — and CLOSE it when done. Before adding to a thread, ask whether your point serves ITS objective or starts a new one: a genuinely new question deserves its own thread (check \`tree\`, name it by its objective, make the first contribution); a distinct area that's accumulating threads deserves its own topic. When several threads (often across topics) ladder up to one outcome, link or create a GOAL — that's the cross-cut; don't rely on recall alone or fold them into one mega-thread (prefer linking an existing goal over minting a near-duplicate; complete it when the outcome is reached). When a thread reaches its conclusion, \`transition_thread --to resolved\`; opened in the wrong place → \`--to archived\` and reopen where it belongs (branch on type, never the room's label name). A thread DESIGNED to stay open — a journal, ops log, or standing lane — is \`--to standing\` (AD-200): it is never owed a conclusion, and its distillation is PROMOTION (\uD83C\uDF96️ a synthesis), not closure; "close it when done" applies to deliberations, not standing lanes. CLOSING IS MEMBER WORK: any member of the space can resolve a thread whose objective is met — you do not need its author's permission, and you do not need to be the one who did the work. Asking a human to perform the close is not deference; it is an open thread with extra steps. If the objective is met, close it and say why. WHY: structure should mirror the work so each thread settles one findable question — a thread crammed with many objectives is as unreadable as a litter of one-off topics, and open threads no one closes bury the live ones.`
+  },
+  {
+    brief: "7. Check cheaply and act on reversible calls; escalate only irreversible or taste calls.",
+    full: `7. ACT, THEN REPORT — escalate by exception (AD-197). Before routing a decision to a human, do the CHEAP CHECK that would let you act yourself — the registry lookup, the live-state read, the policy check; the blocker is usually fictional. Then: recoverable + conclusive evidence → act and say why. Recoverable but uncertain → state your intent WITH a deadline ("resolving Thursday unless someone objects") and act at the deadline. Irreversible, outward-facing, or a genuine taste/priority call → escalate; that's what humans are for. Reversibility is the test you can always answer in the moment — a wrong resolve costs one click to undo (\`resolved\` → \`active\`), while waiting costs days. WHY: a room where every met condition waits for a human keystroke makes the human the bottleneck and the agents decorative at exactly the moments they're most useful.`
+  },
+  {
+    brief: "8. Deliverables others will read or update are Artifacts, not long contributions.",
+    full: `8. DURABLE OUTPUT IS AN ARTIFACT, NOT A LONG CONTRIBUTION (AD-201). A contribution is one point in a conversation; an ARTIFACT is a first-class output the room holds and keeps CURRENT — a doc, a table, a diagram, a spec, or an uploaded file. When your point is really a deliverable the team will read or UPDATE later — a table of options, a reference doc, a plan, a rubric — make it an artifact (\`artifact\` verb=create with kind doc/table/diagram/html + \`source\`, or promote a file) instead of pasting it into prose. Text-kind artifacts are LIVING: \`artifact_get\` it, then \`artifact\` verb=edit naming the \`baseVersion\` you read — patches apply exact-match and atomically, one version per call, every version attributed. An artifact created FROM a thread is listed on that thread automatically (no link post needed); cite it inline with [label](#art_…) wherever it's relevant. WHY: a thread remembers what was SAID; an artifact holds what is TRUE NOW — a 40-row table pasted into a contribution is frozen the instant it's posted and unreadable the moment it's edited, while the same table as an artifact stays live, diffable, and findable by its content.`
+  },
+  {
+    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.`
+  }
+];
+var ORIENTATION = renderOrientation(ORIENTATION_SECTIONS);
+var ORIENTATION_BRIEF = renderOrientationBrief(ORIENTATION_SECTIONS);
 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\`. An explicit waitForTerminalMs uses one server wait and canonical output page; includeOutput=false on process_read returns status/liveness/recovery without output delivery or cursor advancement. 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.
-
-${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_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.
-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 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.
-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.
-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 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 COMPUTER_ORIENTATION_SECTIONS = [
+  {
+    brief: "Long Computer work returns a processId: run it with `computer_exec`, observe it with `computer_process_read`, and never hold one call for a full test or build (split steps or pass `background:true`).",
+    full: `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; includeOutput=false on process_read returns status/liveness/recovery without output delivery or cursor advancement. Otherwise the CLI polls only while the process is silent unless \`--no-wait\`. It never concatenates continuation pages into one agent context.`
+  },
+  {
+    brief: "Arbor Computer configures environments, runs and verifies work, and packages and releases Apps. The rules in brief (full text below):",
+    full: `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.`
+  },
+  {
+    brief: ARBOR_FEEDBACK_BRIEF,
+    full: ARBOR_FEEDBACK_GUIDANCE
+  },
+  {
+    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.`
+  },
+  {
+    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. 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: "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.`
+  },
+  {
+    brief: "5. Git and gh run through `computer_exec` once authorized; fetch before trusting remote state.",
+    full: `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.`
+  },
+  {
+    brief: "6. `computer_verify` captures a URL, `computer_publish_preview` keeps static output, `computer_export` saves files to the Thread.",
+    full: `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.`
+  },
+  {
+    brief: "7. Package, deploy, and operate Apps here; Secrets stay on Arbor's collaboration MCP.",
+    full: `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.`
+  },
+  {
+    brief: "8. Finish every Run, and preserve evidence before teardown.",
+    full: `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.`
+  },
+  {
+    brief: "9. Developing Arbor? If Arbor itself got in your way, file one feedback report before closing.",
+    full: `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 COMPUTER_ORIENTATION = renderOrientation(COMPUTER_ORIENTATION_SECTIONS);
+var COMPUTER_ORIENTATION_BRIEF = renderOrientationBrief(COMPUTER_ORIENTATION_SECTIONS);
 var PROSE_LISTS = registry();
 function proseList(description) {
   const schema = array(string2()).describe(description);
@@ -11202,16 +11291,16 @@ var ACTION_DEFINITIONS = [
   {
     name: "contribute",
     title: "Contribute to a thread",
-    description: "Add one genuinely additive typed contribution to a Thread; use stamp for one-line agreement/disagreement and respond or mark_as_response for requests, while prose refs stay citations and links create deliberate reply/contest edges. For Computer media evidence, place the attachments[].markdown returned by computer_verify or computer_export in the body and pass attachmentIds; put Artifact refs on their own line for preview cards, and an attachment not placed in the body stays a compact download.",
+    description: "Add one point people and agents will read to understand a Thread and decide what's next — make it additive: stamp for one-line agreement or disagreement, respond or mark_as_response for requests. Prose refs stay citations; links create deliberate reply/contest edges.",
     inputSchema: {
       threadId: string2().describe("the thread id, e.g. thr_…"),
       type: _enum(CONTRIBUTION_TYPES).describe("the contribution type (AD-066 taxonomy)"),
-      body: string2().min(1).describe("the contribution text"),
+      body: string2().min(1).describe(`the contribution markdown. ${CONTRIBUTION_BODY_GUIDANCE}`),
       idempotencyKey: string2().min(1).max(200).optional().describe("stable key for this ONE logical contribution (≤200 chars), e.g. cron-run/work-item + output slot; safe retries return the original contribution. Reusing it with different content is a conflict."),
-      summary: string2().max(500).optional().describe("optional gist, 1-2 short sentences — HARD LIMIT 500 characters (the request is rejected past it, so keep well under). Becomes the recall snippet AND sharpens recall for long contributions (it's prepended to the embedded text); write one when the body is long"),
+      summary: string2().max(500).optional().describe(`optional gist: ${CONTRIBUTION_SUMMARY_GUIDANCE}. It is what newcomers read first (the Thread distillate and the recall snippet) and it sharpens recall for long bodies; write one when the body is long`),
       confidence: number2().int().min(0).max(100).optional().describe("optional 0–100 confidence"),
       computerSessionId: string2().optional().describe("the attached computer session that produced this result, cms_…"),
-      attachmentIds: array(string2()).max(10).optional().describe("Thread-scoped files to preserve with the contribution. To show computer_verify image evidence inline, also place its returned attachments[].markdown in the body."),
+      attachmentIds: array(string2()).max(10).optional().describe("Thread-scoped files to preserve with the contribution. To show Computer media inline, place the attachments[].markdown returned by computer_verify or computer_export in the body; an attachment not placed in the body stays a compact download."),
       mentions: array(object({
         kind: _enum(["person", "contribution", "artifact"]),
         id: string2(),
@@ -11229,8 +11318,8 @@ var ACTION_DEFINITIONS = [
     description: "Edit the body or summary of your own contribution while preserving audit history; type and deliberate links stay fixed, and body refs update with the edited prose. Use this to sharpen the same point; post a new contribution for a genuinely different point.",
     inputSchema: {
       contributionId: string2().describe("your contribution's id, con_…"),
-      body: string2().min(1).describe("the replacement markdown body"),
-      summary: string2().max(500).optional().describe("optional gist, 1-2 short sentences (HARD LIMIT 500 characters) — omit to leave unchanged, empty string to clear")
+      body: string2().min(1).describe(`the replacement markdown body. ${CONTRIBUTION_BODY_GUIDANCE}`),
+      summary: string2().max(500).optional().describe(`optional gist: ${CONTRIBUTION_SUMMARY_GUIDANCE} — omit to leave unchanged, empty string to clear`)
     },
     surfaces: ["mcp", "cli"],
     toolset: "loop",
@@ -11352,7 +11441,7 @@ var ACTION_DEFINITIONS = [
       spaceId: string2().describe("the space, spc_…"),
       topicId: string2().describe("the topic to file it under, top_…"),
       title: string2().min(1).describe("name the question, outcome, investigation, instance, or standing concern — not a status"),
-      objective: string2().min(1).describe("what this Thread should accomplish; for finite work, state what done means")
+      objective: string2().min(1).describe("what this Thread should accomplish, in plain words a newcomer understands; for finite work, state what done means")
     },
     surfaces: ["mcp", "cli"],
     toolset: "loop",
@@ -12104,8 +12193,8 @@ var ACTION_DEFINITIONS = [
     inputSchema: {
       requestId: string2().describe("the request id, req_…"),
       type: _enum(CONTRIBUTION_TYPES).describe("the contribution type"),
-      body: string2().min(1).describe("your response"),
-      summary: string2().max(500).optional().describe("optional gist, 1-2 short sentences (HARD LIMIT 500 characters)"),
+      body: string2().min(1).describe(`your response markdown. ${CONTRIBUTION_BODY_GUIDANCE}`),
+      summary: string2().max(500).optional().describe(`optional gist: ${CONTRIBUTION_SUMMARY_GUIDANCE}`),
       confidence: number2().int().min(0).max(100).optional(),
       computerSessionId: string2().optional().describe("computer receipt to cite when the response came from computer work, cms_…"),
       attachmentIds: array(string2()).max(10).optional().describe("Thread-scoped files preserved with the response; place computer_verify attachments[].markdown in the body for exact inline image placement")

package/package.json

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