@sema-agent/server 1.322.0 → 2.0.0

package/dist/capabilities/prompts/code-review.js

@@ -1,3 +1,10 @@
+/**
+ * Code-review council copy (bundle-data layer). Pure data — placeholders are `{name}`-style,
+ * filled by the consumer (code-review-council.ts fillPrompt). Guardrail rationale lives with the
+ * consumer's comments; this file is ONLY the words.
+ */
+/** The deployment-owned lens roster. Order = priority (security/correctness first = the bug-finders);
+ *  the caller dials COUNT only (pickLenses), never a named subset. */
 export const REVIEW_LENSES = [
     { name: "security", brief: "authz/ownership checks, input validation, injection (SQL/command/path), secrets, unsafe deserialization, SSRF, trust boundaries" },
     { name: "correctness", brief: "edge cases, off-by-one, race conditions, resource leaks, missing/incorrect error paths, unhandled rejections" },
@@ -6,6 +13,8 @@ export const REVIEW_LENSES = [
     { name: "tests", brief: "are the risky paths covered? do tests assert behavior (not implementation)? missing edge-case tests" },
     { name: "readability", brief: "naming, dead code, duplication, misleading comments, structure — these are [DESIGN], never [BUG]" },
 ];
+/** Guardrails 2-5: evidence grounding (a CONFIDENCE signal, not a delete), requirement anchoring,
+ *  bucketing, severity×confidence. */
 export const GROUNDING = [
     "RULES:",
     "1. EVIDENCE drives CONFIDENCE (it does NOT delete a finding): cite an exact `path:line` and, whenever you can, **paste the verbatim code snippet** you are flagging. A finding WITH a pasted snippet may carry full confidence/severity; a finding with only a line reference is still allowed but MUST be tagged `[unverified: line-ref only]` and capped at minor severity / low confidence (never a blocker).",
@@ -13,17 +22,21 @@ export const GROUNDING = [
     "3. BUCKET: label each finding [BUG] (provably wrong against the code), [DESIGN] (subjective preference), or [QUESTION]. A design preference is NEVER a [BUG].",
     "4. RATE each: severity (blocker/major/minor) AND confidence (high/med/low).",
 ].join("\n");
+/** L1 lens reviewer system prompt. Placeholders: {name} {brief} {grounding}. */
 export const LENS_SYSTEM_TPL = "You are a {name} code reviewer. Stay strictly in your lane: {brief}.\n" +
     "Read only the files you need — repo_tree to map, then repo_read_file (just-in-time).\n\n{grounding}\n\n" +
     'List findings in your lens only. If you find nothing solid, say "no findings".';
+/** L2 peer-debate persona (guardrails 5,6). Placeholders: {name} {brief}. */
 export const DEBATE_MEMBER_TPL = "You are the {name} reviewer on a review panel ({brief}). Cross-examine the findings in " +
     "the shared transcript: CORROBORATE or REBUT others' claims in your area (raising/lowering their " +
     "confidence), and DEFEND or WITHDRAW your own if rebutted.\n" +
     "You MAY call repo_read_file to VERIFY ONE specific DISPUTED finding (quote the exact path:line) — do " +
     "NOT re-review the whole repo. A finding with no path:line + code quote is invalid. Be concise.";
+/** L2 debate topic body. Placeholders: {objective} {grounding} {findings}. */
 export const DEBATE_TOPIC_TPL = "Cross-examine these specialist code-review findings for: {objective}\n\n{grounding}\n" +
     "5. CONFIDENCE: peer corroboration raises it; an unrebutted rebuttal lowers it; drop findings that " +
     "collapse under scrutiny.\n\nFindings to debate:\n\n{findings}";
+/** Guardrails 4,7: arbitration is not summary — no new findings, ground/dedup/bucket/rank only. */
 export const ARBITER_SYSTEM = "You are the NEUTRAL ARBITER of a code-review council. You are given findings from independent " +
     "specialist reviewers. You do NOT add new findings and do NOT re-review. Your only job:\n" +
     "- TIER by grounding, do NOT silently drop real findings: a finding that PASTES the code keeps its " +
@@ -35,5 +48,6 @@ export const ARBITER_SYSTEM = "You are the NEUTRAL ARBITER of a code-review coun
     "Output the final review: a 2-3 line summary, then findings grouped by bucket then severity, each as " +
     "`path:line` — the problem — a concrete fix. Never invent files or symbols. If a whole lens reported " +
     "nothing groundable, say so rather than inventing.";
+/** No-arbiter fallback header ({findings} appended by the consumer). */
 export const ARBITER_FALLBACK_HEADER = "[council 仲裁无输出——以下是未经仲裁的各 lens 原始发现]\n\n";
 //# sourceMappingURL=code-review.js.map

package/dist/capabilities/prompts/identity.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Sema identity — the branded role layer for the `default` scenario (bundle-data layer; wording
+ * history: neutralized — no baked model/vendor/protocol facts, because the brain
+ * stack has both OpenAI-compatible AND Anthropic-compatible legs and any baked substrate claim is the same
+ * class of lie the neutralization removed. The anti-"I am Claude" design is kept.)
+ */
 export declare const SEMA_IDENTITY: string;
 //# sourceMappingURL=identity.d.ts.map

package/dist/capabilities/prompts/identity.js

@@ -1,3 +1,9 @@
+/**
+ * Sema identity — the branded role layer for the `default` scenario (bundle-data layer; wording
+ * history: neutralized — no baked model/vendor/protocol facts, because the brain
+ * stack has both OpenAI-compatible AND Anthropic-compatible legs and any baked substrate claim is the same
+ * class of lie the neutralization removed. The anti-"I am Claude" design is kept.)
+ */
 export const SEMA_IDENTITY = "You are Sema, an AI agent built by the Sema team. You act through tools to get real work done.\n" +
     "You run on a large language model chosen and configured by your operator — you are NOT Claude, NOT " +
     "GPT, and NOT made by Anthropic or OpenAI. If asked who you are or which model you are, answer honestly " +

package/dist/capabilities/prompts/team.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Built-in team personas (bundle-data layer) — GENERIC personas only; the business prompt is
+ * appended at call time by the consumer (team.ts), never baked in here.
+ */
 export declare const TEAM_PERSONAS: {
     readonly analyst: "You analyze the task: lay out the key considerations, options, and trade-offs. Be concrete.";
     readonly critic: "You challenge the analysis: surface gaps, wrong assumptions, risks, and stronger alternatives.";

package/dist/capabilities/prompts/team.js

@@ -1,3 +1,7 @@
+/**
+ * Built-in team personas (bundle-data layer) — GENERIC personas only; the business prompt is
+ * appended at call time by the consumer (team.ts), never baked in here.
+ */
 export const TEAM_PERSONAS = {
     analyst: "You analyze the task: lay out the key considerations, options, and trade-offs. Be concrete.",
     critic: "You challenge the analysis: surface gaps, wrong assumptions, risks, and stronger alternatives.",

package/dist/capabilities/repo-tools.d.ts

@@ -1,9 +1,19 @@
 import type { ToolSpec } from "@sema-agent/core";
+/**
+ * Read-only repository tools backed by a Git host (Gitea) HTTP API — NOT a clone/shell on the runner.
+ *
+ * The agent reads a repo just-in-time (tree → read file → PR diff) through scoped function tools; the
+ * read token lives only in this server-side client (never in the model/sandbox), and tools are bound
+ * to exactly the repo the task was given. This is the lightweight path for code review (read + reason);
+ * running tests/linters would need a sandboxed ExecutionEnv (a deliberate future extension, not here).
+ */
 export interface RepoCoords {
     owner: string;
     repo: string;
 }
+/** Parse `owner/name` or a repo URL (e.g. http://host:9999/AI-Only/sema-server.git). */
 export declare function parseRepo(input: string): RepoCoords;
+/** Thin read-only Gitea API client. Built once at startup; bound to a repo per task. */
 export declare class GiteaClient {
     private readonly baseUrl;
     private readonly token?;
@@ -15,5 +25,6 @@ export declare class GiteaClient {
     readFile(coords: RepoCoords, path: string, ref: string): Promise<string>;
     pullDiff(coords: RepoCoords, index: number): Promise<string>;
 }
+/** Build the read-only repo tool set bound to one repo (cheap per-task closure; the client is shared). */
 export declare function repoToolsFor(client: GiteaClient, coords: RepoCoords): ToolSpec[];
 //# sourceMappingURL=repo-tools.d.ts.map

package/dist/capabilities/repo-tools.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+/** Parse `owner/name` or a repo URL (e.g. http://host:9999/AI-Only/sema-server.git). */
 export function parseRepo(input) {
     const s = input.trim().replace(/\.git$/, "");
     const m = /^[a-z]+:\/\/[^/]+\/(.+)$/i.exec(s);
@@ -10,7 +11,9 @@ export function parseRepo(input) {
 }
 const MAX_FILE_BYTES = 96 * 1024;
 const MAX_TREE_ENTRIES = 2000;
+/** Bound each Git-host call so a slow/hung host can't pin a review lens to its whole deadline. */
 const REQUEST_TIMEOUT_MS = 15_000;
+/** Thin read-only Gitea API client. Built once at startup; bound to a repo per task. */
 export class GiteaClient {
     baseUrl;
     token;
@@ -43,6 +46,10 @@ export class GiteaClient {
     }
     async readFile(coords, path, ref) {
         const { owner, repo } = coords;
+        // `encodeURIComponent` does NOT escape "." — so a `..` segment survives the per-segment encode and the
+        // WHATWG URL parser collapses it when `fetch` builds the request, letting a crafted `path` climb out of
+        // `/repos/<owner>/<repo>/contents/` to any endpoint the read token can reach (cross-repo / admin). The
+        // tools are contractually bound to exactly one repo (see header), so reject traversal before it hits fetch.
         const segments = path.split("/").filter(Boolean);
         if (segments.some((s) => s === "..")) {
             throw new Error(`invalid path "${path}" (".." segments are not allowed)`);
@@ -62,6 +69,7 @@ export class GiteaClient {
         return text.length > MAX_FILE_BYTES * 4 ? text.slice(0, MAX_FILE_BYTES * 4) + "\n…[diff truncated]" : text;
     }
 }
+/** Build the read-only repo tool set bound to one repo (cheap per-task closure; the client is shared). */
 export function repoToolsFor(client, coords) {
     const ref = (r) => (r ? Promise.resolve(r) : client.defaultBranch(coords));
     return [

package/dist/capabilities/sandbox-file-send.d.ts

@@ -1,24 +1,119 @@
+/**
+ * SendUserFile v2 — the sandbox-lane file source (clay ruling 2026-07-14: Plan B direct upload).
+ *
+ * The tool cannot reach the task's sandbox through core (ToolExecuteContext carries no env handle — core
+ * keeps the per-task ExecutionEnv private to its prepare-task closure). But the server BUILDS the
+ * `executionEnvFactory` core calls, and the factory context carries `taskId` — so we wrap OUR OWN factory
+ * (same posture as withWorktreeIsolation) and keep a replica-local taskId → env registry, unregistering
+ * when core destroys the env. No core change, no parallel abstraction — pure deployment glue on a seam
+ * the deployment already owns.
+ *
+ * The send itself is the anti-relay shape ([747]; k8s workspace-snapshot posture): the server presigns a
+ * single-object PUT (120s, method-bound, STAGING key — 修3), the SANDBOX `curl -T`s the file straight to S3 — bytes never
+ * relay through the server, S3 credentials never enter the sandbox. Tenant isolation = the sandbox can
+ * only read its own filesystem, which is exactly the tenant's task workspace; that is why this lane is
+ * multi-tenant-safe while the host lane never is (host-lane multi-tenant is permanently closed).
+ *
+ * ssh lane (backfill 2026-07-14): the SAME send chain works over the ssh adapter unchanged — its exec
+ * face is contract-identical (Result{stdout,stderr,exitCode}, stderr split, `options.timeout` in SECONDS
+ * ×1000, remote-env-ssh.ts) and the peer is assumed LINUX (`stat -c %s` = GNU/busybox; the fleet is all
+ * Linux — a macOS peer's `stat -f %z` dialect would fail LOUD at the exit-code/stat-parse guards, never
+ * silently). But the TENANT judgment INVERTS: an ssh peer is ONE persistent real machine shared by every
+ * task (sshExecutionEnvFactory ignores ctx — same host + same mountPath for all tasks; destroy() only
+ * disconnects, files persist; capabilities.isolation:false). "Scoped read = tenant boundary" does NOT
+ * hold there, so the ssh lane is SINGLE-USER ONLY (same gate as host) — see `sandboxSendLaneEnabled`.
+ *
+ * The presigned PUT URL is a capability secret: it never enters model context (the tool returns delivery
+ * metadata only) and is REDACTED from every error surfaced from here (curl stderr may echo the URL).
+ *
+ * RESIDUAL CLOSED (修3, 三路复审 2026-07-15; was the accepted dual-review residual of 2026-07-14): the URL
+ * still rides the exec command line (readable via /proc inside the sandbox), but it is now a capability on
+ * a STAGING key only — the server promotes staging→final with its own creds (CopyObject), deletes staging,
+ * and size-verifies the FINAL object, whose write URL never existed outside the server. A /proc reader can
+ * no longer rewrite the delivered object after verification or skew the ledgered size (see
+ * PreparedDirectUpload in send-user-file.ts for the full promotion contract).
+ */
 import type { ExecutionEnv, ExecutionEnvFactory } from "@sema-agent/core";
 import type { IssuedFileLink, PreparedDirectUpload } from "../plugins/send-user-file.js";
+/** Leak backstop (codex review HIGH): core skips destroy on suspend/review paths and a crash may skip it
+ *  entirely — the suspendVM wrap covers the common case, this bound covers the rest. Far above any real
+ *  per-replica concurrency. 修6: at the cap the registry REFUSES the new registration instead of FIFO-evicting
+ *  the oldest entry — every entry here is live-until-destroy/suspend by construction, so there is no
+ *  "terminal/stale" liveness verdict to evict on, and silently breaking an EXISTING live task's send face to
+ *  admit a new one inverts the harm (the old FIFO victim's SendUserFile would report "no sandbox attached"
+ *  while its env kept executing). The refused task gets a TYPED capacity error at send time instead. */
 export declare const TASK_ENV_REGISTRY_MAX = 512;
+/** Replica-local taskId → live ExecutionEnv(s). Registered by the factory wrap, dropped on destroy/suspend.
+ *
+ *  修5 (concurrent-generation guard): deployments WITHOUT a run-store single-active-session claim can race
+ *  two legs of one session through the factory concurrently — previously the second registration silently
+ *  OVERWROTE the first, so leg A's later SendUserFile resolved to leg B's env (wrong-generation read/upload).
+ *  The registry now keeps EVERY live env per key and `get()` fail-louds on ambiguity: neither leg can silently
+ *  read the other's sandbox, and the moment one generation is destroyed/suspended the survivor resolves again.
+ *  (Rejecting the second factory call outright was considered and discarded: a stale never-destroyed entry —
+ *  crash/no-destroy path — would then brick every future leg of that task, and the factory seam must not fail
+ *  env creation for a send-face bookkeeping conflict. Deployments WITH the single-active-session claim
+ *  serialize legs upstream and never see this state.) */
 export declare class TaskEnvRegistry {
     private readonly map;
+    /** 修6: taskIds whose registration was refused at the cap — lets get() report the TRUE reason (typed
+     *  capacity error, not a misleading "no sandbox attached"). Bounded by the same cap (marker-only). */
     private readonly refusedAtCapacity;
     private liveCount;
+    /** Resolve the ONE live env for a task. Throws typed errors on the two governed failure states:
+     *  ambiguity (修5 — concurrent generations both live) and capacity refusal (修6). Returns undefined when
+     *  the task simply has no registered env (caller reports "no sandbox attached"). */
     get(taskId: string | undefined): ExecutionEnv | undefined;
+    /** Wrap the deployment's own factory: register each minted env under the task's CANONICAL id — core hands
+     *  the factory the raw `spec.taskId` but gives tools `hostTaskId = spec.taskId ?? sessionId` (prepare-task
+     *  262/320/428; the sync `/v1/tasks` leg deliberately sets no spec.taskId), so the registry key MUST apply
+     *  the same fallback or every sync-leg lookup misses (codex review HIGH). Unregister when core calls
+     *  destroy() (identity guard: only the env's OWN entry is dropped — a replacement env for a reused key must
+     *  not be evicted by the old one's late destroy). core SKIPS destroy on durable suspend/review (runtask
+     *  keeps the env for the snapshot) — wrap suspendVM the same way so a suspended task doesn't pin its env
+     *  here forever; the bounded-size backstop covers any remaining no-destroy crash path. */
     wrapFactory(factory: ExecutionEnvFactory): ExecutionEnvFactory;
 }
+/**
+ * Which REMOTE_EXEC lanes may register the sandbox-send TaskEnvRegistry (and thus mount the sandbox-lane
+ * SendUserFile source), under which tenancy gate. The judgment per lane (2026-07-14 ssh backfill review):
+ *
+ *  - e2b / k8s: one task = one disposable sandbox; the sandbox filesystem IS the tenant's task workspace,
+ *    so a sandbox-scoped read is tenant-scoped by construction → open to any tenant.
+ *  - ssh: the peer is ONE persistent real machine SHARED across tasks (factory ignores ctx: every task
+ *    gets the same host+mountPath; destroy=disconnect only, files persist). Tenant A's task can read the
+ *    residue of tenant B's task → the isolation premise FAILS. Multi-tenant here would be an
+ *    arbitrary-host-path-read → public-URL exfil face, so the lane opens ONLY single-user
+ *    (`requirePrincipal !== true`), the exact gate the host lane uses. NOT a lane to "fix later with a
+ *    per-task workspace": tasks legitimately operate outside any workspace on a real host (design/61 —
+ *    batch deployment), so per-task dirs would not restore the boundary anyway.
+ *  - adb / local-docker / host / unset: no registry (host+unset use the local-fs source in main.ts;
+ *    adb/local-docker remain a follow-on).
+ */
 export declare function sandboxSendLaneEnabled(provider: string | undefined, requirePrincipal: boolean): boolean;
+/** Single-quote a path for POSIX sh (the only metacharacter inside '' is ' itself). */
 export declare function shq(s: string): string;
+/** Strip the capability URL (and any SigV4 signature) from text before it reaches an error/log — including
+ *  the percent-encoded forms an adapter may echo (the k8s exec transport carries the command in a request
+ *  URI, so an error can quote the URL re-encoded; codex review MED). */
 export declare function redactPutUrl(text: string, url: string): string;
 export interface SandboxFileSendDeps {
     registry: TaskEnvRegistry;
+    /** `scope` = the caller's VERIFIED principal (ToolExecuteContext.principal) — keys the hashed scope segment
+     *  in the object key + rides back on IssuedFileLink.scope for the ledger. Absent on single-user lanes. */
     prepare: (filename: string | undefined, scope?: string) => PreparedDirectUpload;
     maxBytes: number;
 }
+/** The live object `createSandboxFileSend` produces — a bare callable (deps captured in closure), mirroring
+ *  the sibling `SendUserFileIssuer` role (send-user-file.ts) one level down: this is the sandbox-lane half. */
 export type SandboxFileSend = (path: string, ctx: {
     taskId?: string;
     principal?: string;
 }) => Promise<IssuedFileLink>;
+/**
+ * The sandbox-lane `send` seam for the SendUserFile tool: in-sandbox stat (existence + regular file +
+ * size cap, BEFORE any signing) → presign PUT → in-sandbox `curl -T` → finalize the user-facing link.
+ * Throws typed Errors (redacted) — the tool reports them per file.
+ */
 export declare function createSandboxFileSend(deps: SandboxFileSendDeps): SandboxFileSend;
 //# sourceMappingURL=sandbox-file-send.d.ts.map

package/dist/capabilities/sandbox-file-send.js

@@ -1,7 +1,27 @@
 import { hasDestroy } from "@sema-agent/core";
+/** Leak backstop (codex review HIGH): core skips destroy on suspend/review paths and a crash may skip it
+ *  entirely — the suspendVM wrap covers the common case, this bound covers the rest. Far above any real
+ *  per-replica concurrency. 修6: at the cap the registry REFUSES the new registration instead of FIFO-evicting
+ *  the oldest entry — every entry here is live-until-destroy/suspend by construction, so there is no
+ *  "terminal/stale" liveness verdict to evict on, and silently breaking an EXISTING live task's send face to
+ *  admit a new one inverts the harm (the old FIFO victim's SendUserFile would report "no sandbox attached"
+ *  while its env kept executing). The refused task gets a TYPED capacity error at send time instead. */
 export const TASK_ENV_REGISTRY_MAX = 512;
+/** Replica-local taskId → live ExecutionEnv(s). Registered by the factory wrap, dropped on destroy/suspend.
+ *
+ *  修5 (concurrent-generation guard): deployments WITHOUT a run-store single-active-session claim can race
+ *  two legs of one session through the factory concurrently — previously the second registration silently
+ *  OVERWROTE the first, so leg A's later SendUserFile resolved to leg B's env (wrong-generation read/upload).
+ *  The registry now keeps EVERY live env per key and `get()` fail-louds on ambiguity: neither leg can silently
+ *  read the other's sandbox, and the moment one generation is destroyed/suspended the survivor resolves again.
+ *  (Rejecting the second factory call outright was considered and discarded: a stale never-destroyed entry —
+ *  crash/no-destroy path — would then brick every future leg of that task, and the factory seam must not fail
+ *  env creation for a send-face bookkeeping conflict. Deployments WITH the single-active-session claim
+ *  serialize legs upstream and never see this state.) */
 export class TaskEnvRegistry {
     map = new Map();
+    /** 修6: taskIds whose registration was refused at the cap — lets get() report the TRUE reason (typed
+     *  capacity error, not a misleading "no sandbox attached"). Bounded by the same cap (marker-only). */
     refusedAtCapacity = new Set();
     liveCount() {
         let n = 0;
@@ -9,6 +29,9 @@ export class TaskEnvRegistry {
             n += envs.length;
         return n;
     }
+    /** Resolve the ONE live env for a task. Throws typed errors on the two governed failure states:
+     *  ambiguity (修5 — concurrent generations both live) and capacity refusal (修6). Returns undefined when
+     *  the task simply has no registered env (caller reports "no sandbox attached"). */
     get(taskId) {
         if (taskId === undefined)
             return undefined;
@@ -23,14 +46,26 @@ export class TaskEnvRegistry {
         }
         return undefined;
     }
+    /** Wrap the deployment's own factory: register each minted env under the task's CANONICAL id — core hands
+     *  the factory the raw `spec.taskId` but gives tools `hostTaskId = spec.taskId ?? sessionId` (prepare-task
+     *  262/320/428; the sync `/v1/tasks` leg deliberately sets no spec.taskId), so the registry key MUST apply
+     *  the same fallback or every sync-leg lookup misses (codex review HIGH). Unregister when core calls
+     *  destroy() (identity guard: only the env's OWN entry is dropped — a replacement env for a reused key must
+     *  not be evicted by the old one's late destroy). core SKIPS destroy on durable suspend/review (runtask
+     *  keeps the env for the snapshot) — wrap suspendVM the same way so a suspended task doesn't pin its env
+     *  here forever; the bounded-size backstop covers any remaining no-destroy crash path. */
     wrapFactory(factory) {
         return async (ctx) => {
             const env = await factory(ctx);
             const taskId = ctx.taskId ?? ctx.sessionId;
             if (hasDestroy(env)) {
                 const existing = this.map.get(taskId);
+                // 修6: refuse NEW keys at the cap (never evict a live entry — see TASK_ENV_REGISTRY_MAX). A same-key
+                // additional registration is always admitted even at the cap: the 修5 ambiguity guard is a correctness
+                // fence and must not be dodgeable by arriving while the registry is full.
                 if (existing === undefined && this.liveCount() >= TASK_ENV_REGISTRY_MAX) {
                     if (this.refusedAtCapacity.size >= TASK_ENV_REGISTRY_MAX) {
+                        // marker set is itself bounded; beyond it the task degrades to the plain "no sandbox attached" report
                         const oldestMarker = this.refusedAtCapacity.values().next().value;
                         if (oldestMarker !== undefined)
                             this.refusedAtCapacity.delete(oldestMarker);
@@ -42,8 +77,10 @@ export class TaskEnvRegistry {
                         clearMarker();
                         return origDestroy();
                     };
-                    return env;
+                    return env; // env itself is untouched — only the send face is refused (typed error at get())
                 }
+                // 修5: append, never overwrite — a live sibling under the same key makes get() fail loud instead of
+                // silently handing one leg the other leg's sandbox.
                 if (existing === undefined)
                     this.map.set(taskId, [env]);
                 else
@@ -52,7 +89,7 @@ export class TaskEnvRegistry {
                     const envs = this.map.get(taskId);
                     if (envs === undefined)
                         return;
-                    const i = envs.indexOf(env);
+                    const i = envs.indexOf(env); // identity guard: drop only THIS env's entry
                     if (i >= 0)
                         envs.splice(i, 1);
                     if (envs.length === 0)
@@ -69,7 +106,7 @@ export class TaskEnvRegistry {
                     suspendable.suspendVM = async (...args) => {
                         const r = await origSuspend(...args);
                         if (r.ok)
-                            evict();
+                            evict(); // suspended env is dormant — the resume leg registers a fresh one
                         return r;
                     };
                 }
@@ -78,6 +115,22 @@ export class TaskEnvRegistry {
         };
     }
 }
+/**
+ * Which REMOTE_EXEC lanes may register the sandbox-send TaskEnvRegistry (and thus mount the sandbox-lane
+ * SendUserFile source), under which tenancy gate. The judgment per lane (2026-07-14 ssh backfill review):
+ *
+ *  - e2b / k8s: one task = one disposable sandbox; the sandbox filesystem IS the tenant's task workspace,
+ *    so a sandbox-scoped read is tenant-scoped by construction → open to any tenant.
+ *  - ssh: the peer is ONE persistent real machine SHARED across tasks (factory ignores ctx: every task
+ *    gets the same host+mountPath; destroy=disconnect only, files persist). Tenant A's task can read the
+ *    residue of tenant B's task → the isolation premise FAILS. Multi-tenant here would be an
+ *    arbitrary-host-path-read → public-URL exfil face, so the lane opens ONLY single-user
+ *    (`requirePrincipal !== true`), the exact gate the host lane uses. NOT a lane to "fix later with a
+ *    per-task workspace": tasks legitimately operate outside any workspace on a real host (design/61 —
+ *    batch deployment), so per-task dirs would not restore the boundary anyway.
+ *  - adb / local-docker / host / unset: no registry (host+unset use the local-fs source in main.ts;
+ *    adb/local-docker remain a follow-on).
+ */
 export function sandboxSendLaneEnabled(provider, requirePrincipal) {
     if (provider === "e2b" || provider === "k8s")
         return true;
@@ -85,9 +138,13 @@ export function sandboxSendLaneEnabled(provider, requirePrincipal) {
         return requirePrincipal !== true;
     return false;
 }
+/** Single-quote a path for POSIX sh (the only metacharacter inside '' is ' itself). */
 export function shq(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
+/** Strip the capability URL (and any SigV4 signature) from text before it reaches an error/log — including
+ *  the percent-encoded forms an adapter may echo (the k8s exec transport carries the command in a request
+ *  URI, so an error can quote the URL re-encoded; codex review MED). */
 export function redactPutUrl(text, url) {
     return text
         .split(url)
@@ -95,25 +152,45 @@ export function redactPutUrl(text, url) {
         .split(encodeURIComponent(url))
         .join("<presigned-put-url>")
         .replace(/X-Amz-Signature(=|%3D)[0-9a-f]+/gi, "X-Amz-Signature=<redacted>")
+        // A PARTIAL URL (adapter truncation/line-wrap) can survive the exact-match passes above — the SigV4
+        // Credential query param carries the ACCESS KEY ID, scrub it independently (defense in depth).
         .replace(/X-Amz-Credential(=|%3D)[^&\s"']+/gi, "X-Amz-Credential=<redacted>");
 }
+/**
+ * The sandbox-lane `send` seam for the SendUserFile tool: in-sandbox stat (existence + regular file +
+ * size cap, BEFORE any signing) → presign PUT → in-sandbox `curl -T` → finalize the user-facing link.
+ * Throws typed Errors (redacted) — the tool reports them per file.
+ */
 export function createSandboxFileSend(deps) {
     return async (path, ctx) => {
         const env = deps.registry.get(ctx.taskId);
         if (!env) {
             throw new Error("no sandbox is attached to this task yet — SendUserFile reads from the task sandbox; retry after the environment has started");
         }
+        // The path is model-controlled and rides a shell line: shq() covers every POSIX metacharacter, but
+        // control chars (NUL truncates argv in some transports; \n splits lines in naive adapters) buy nothing
+        // legitimate — reject outright rather than trust each adapter's quoting edge.
         if (/[\u0000-\u001f\u007f]/.test(path))
             throw new Error("file path contains control characters — not a valid sandbox path");
         if (path.length > 4096)
             throw new Error("file path exceeds 4096 characters — not a valid sandbox path");
+        // `curl -T -` means STDIN by convention — a relative path starting with '-' must ride as ./-name so all
+        // three sites (test operand / stat / curl) name the same real file.
         const q = shq(path.startsWith("-") ? `./${path}` : path);
+        // stat first: fail before minting any capability URL. `test -f` = regular file only (no dirs/devices);
+        // `stat -c %s` = GNU/busybox size (sandbox images are Linux; the ssh lane assumes a LINUX peer — the
+        // whole fleet is — a macOS peer would exit non-zero here and fail loud, see the module header).
+        // ExecutionEnv.exec timeout is SECONDS (e2b, k8s AND ssh adapters all multiply by 1000 — codex
+        // review MED caught ms here; ssh reading = remote-env-ssh.ts `options.timeout * 1000`).
         const stat = await env.exec(`test -f ${q} && stat -c %s -- ${q}`, { timeout: 30 });
         if (!stat.ok)
             throw new Error(`sandbox stat failed: ${stat.error.message}`);
         if (stat.value.exitCode !== 0) {
             throw new Error(`file not found in the sandbox (or not a regular file): ${path} — ls first; absolute paths are safest`);
         }
+        // Advisory pre-check only (the authoritative size accounting is server-side verifySize below — the
+        // sandbox owns its filesystem, so nothing it reports is binding): still worth failing early and cheap.
+        // Strict digit match, not bare parseInt — a digit-prefixed garbled line must fail loud, not truncate.
         const statOut = stat.value.stdout.trim();
         if (!/^\d+$/.test(statOut))
             throw new Error(`sandbox stat returned an unparsable size for ${path}: ${statOut}`);
@@ -123,7 +200,15 @@ export function createSandboxFileSend(deps) {
         }
         const filename = path.split(/[/\\]/).pop();
         const prepared = deps.prepare(filename, ctx.principal);
+        // Everything from here can echo the capability URL (adapter throws included, not just Result errors —
+        // codex review MED) — one redacting fence around the whole upload phase.
         try {
+            // -f: HTTP >= 400 → exit 22 (no silent half-uploads). NO -s: the progress meter on stderr feeds the
+            // e2b/k8s adapters' ~120s zero-output liveness watchdog — a silent multi-minute upload would be killed
+            // as a hang (the k8s snapshot lane solves this with livenessMs:0; a chatty meter is the seam-free way).
+            // The ssh adapter has NO idle-output watchdog on exec() (total-timeout bound only) — the meter is
+            // harmless noise there, so one shared command shape serves all three lanes.
+            // stderr may echo the URL → the redact fence below covers every throw out of this block.
             const up = await env.exec(`curl -f -T ${q} ${shq(prepared.putUrl)}`, { timeout: 300 });
             if (!up.ok)
                 throw new Error(`sandbox upload failed: ${up.error.message}`);
@@ -133,6 +218,9 @@ export function createSandboxFileSend(deps) {
                     throw new Error("sandbox upload failed: curl is not available in this sandbox image");
                 throw new Error(`sandbox upload failed (curl exit ${up.value.exitCode})${detail.length > 0 ? `: ${detail}` : ""}`);
             }
+            // Server-side accounting is authoritative (codex review HIGH: stat→curl is an exploitable TOCTOU —
+            // swap/grow the file between the two and the cap is bypassed with a stale size on the card): HEAD the
+            // real object; over-cap ⇒ deleted inside verifySize; the card carries the verified size.
             const verifiedSize = await prepared.verifySize(deps.maxBytes);
             return prepared.finalize(verifiedSize);
         }