@sema-agent/core 2.13.0 → 3.0.0

package/dist/prompt-assembly/tool-catalog.js

@@ -1,4 +1,12 @@
 import { createHash } from "node:crypto";
+const PRESENTATION_KEYWORDS = new Set(["description", "title", "examples", "$id"]);
+const SCHEMA_NAME_MAPS = new Set([
+    "properties",
+    "patternProperties",
+    "definitions",
+    "$defs",
+    "dependentSchemas",
+]);
 function stripPresentation(node) {
     if (Array.isArray(node))
         return node.map(stripPresentation);
@@ -6,8 +14,15 @@ function stripPresentation(node) {
         return node;
     const out = {};
     for (const [k, v] of Object.entries(node)) {
-        if (k === "description" || k === "title" || k === "examples" || k === "$id")
+        if (PRESENTATION_KEYWORDS.has(k))
             continue;
+        if (SCHEMA_NAME_MAPS.has(k) && v !== null && typeof v === "object" && !Array.isArray(v)) {
+            const named = {};
+            for (const [name, sub] of Object.entries(v))
+                named[name] = stripPresentation(sub);
+            out[k] = named;
+            continue;
+        }
         out[k] = k === "required" && Array.isArray(v) ? [...v].sort() : stripPresentation(v);
     }
     return out;

package/dist/prompt-assembly/turn-snapshot.js

@@ -61,7 +61,10 @@ export function buildTurnPromptSnapshot(raw, api, promptHasher) {
         loweringVersion: `${lowering.version}/${lowering.form}/${api}`,
     };
     const bump = () => {
-        snapshot.cacheIdentity = identityOf(elements);
+        const next = identityOf(elements);
+        if (next === snapshot.cacheIdentity)
+            return;
+        snapshot.cacheIdentity = next;
         snapshot.onChange?.(snapshot);
     };
     const snapshot = {

package/dist/stores/file/fs-atomic.d.ts

@@ -10,7 +10,10 @@ export declare class AppendLog {
     private fd;
     private disposed;
     private readonly path;
+    private boundary;
     constructor(path: string);
+    private sizeOrUnknown;
+    private repairTornTail;
     append(record: unknown, fsync: boolean): void;
     close(): void;
     closeForSwap(): void;

package/dist/stores/file/fs-atomic.js

@@ -1,4 +1,4 @@
-import { closeSync, constants as FS, existsSync, linkSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, truncateSync, unlinkSync, writeFileSync, writeSync, fsyncSync, } from "node:fs";
+import { closeSync, constants as FS, existsSync, fstatSync, linkSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, truncateSync, unlinkSync, writeFileSync, writeSync, fsyncSync, } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve as resolvePath } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
@@ -148,30 +148,75 @@ export class AppendLog {
     fd;
     disposed = false;
     path;
+    boundary = -1;
     constructor(path) {
         this.path = path;
         ensureDir(dirnameOf(path));
         truncateTornTail(path);
-        this.fd = openSync(path, "a", 0o600);
+        this.fd = openSync(path, "a+", 0o600);
+        this.boundary = this.sizeOrUnknown();
+    }
+    sizeOrUnknown() {
+        try {
+            return fstatSync(this.fd).size;
+        }
+        catch {
+            return -1;
+        }
+    }
+    repairTornTail() {
+        const size = this.sizeOrUnknown();
+        if (size < 0) {
+            this.boundary = -1;
+            return;
+        }
+        if (size === this.boundary)
+            return;
+        if (size === 0) {
+            this.boundary = 0;
+            return;
+        }
+        const tail = Buffer.allocUnsafe(1);
+        try {
+            if (readSync(this.fd, tail, 0, 1, size - 1) === 1 && tail[0] === 0x0a) {
+                this.boundary = size;
+                return;
+            }
+        }
+        catch {
+            return;
+        }
+        truncateTornTail(this.path);
+        this.boundary = this.sizeOrUnknown();
     }
     append(record, fsync) {
         if (this.fd < 0 && !this.disposed) {
             truncateTornTail(this.path);
-            this.fd = openSync(this.path, "a", 0o600);
+            this.fd = openSync(this.path, "a+", 0o600);
+            this.boundary = this.sizeOrUnknown();
         }
         if (this.fd < 0) {
             const e = new Error("append: this log was closed (its session/box was deleted or replaced) — refusing to write through a released descriptor");
             e.code = "log_closed";
             throw e;
         }
+        this.repairTornTail();
         const buf = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
         let written = 0;
-        while (written < buf.length) {
-            const n = writeSync(this.fd, buf, written, buf.length - written);
-            if (n <= 0)
-                throw new Error(`append: write made no progress (${written}/${buf.length} bytes) — refusing to leave a torn record`);
-            written += n;
+        try {
+            while (written < buf.length) {
+                const n = writeSync(this.fd, buf, written, buf.length - written);
+                if (n <= 0)
+                    throw new Error(`append: write made no progress (${written}/${buf.length} bytes) — refusing to leave a torn record`);
+                written += n;
+            }
+        }
+        catch (err) {
+            this.boundary = -1;
+            throw err;
         }
+        if (this.boundary >= 0)
+            this.boundary += buf.length;
         if (fsync)
             fsyncSync(this.fd);
     }

package/dist/stores/file/index.d.ts

@@ -38,6 +38,7 @@ export declare class FileStorageBackend {
     private readonly fileCheckpoints;
     private readonly fileMemory;
     private readonly ttl;
+    private readonly fileSessions;
     private readonly fileWorkflowJournal;
     constructor(opts?: FileStorageBackendOptions);
     dispose(): Promise<void>;

package/dist/stores/file/index.js

@@ -32,6 +32,7 @@ export class FileStorageBackend {
     fileCheckpoints;
     fileMemory;
     ttl;
+    fileSessions;
     fileWorkflowJournal;
     constructor(opts = {}) {
         this.root = resolveDataRoot(opts.root);
@@ -39,6 +40,7 @@ export class FileStorageBackend {
         this.lock.acquire();
         try {
             const repo = new FileSessionRepo(this.root);
+            this.fileSessions = repo;
             this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget" });
             this.sessionStore = this.ttl;
             this.fileCheckpoints = new FileCheckpointStore(this.root, opts.checkpoint);
@@ -63,6 +65,11 @@ export class FileStorageBackend {
         }
         catch {
         }
+        try {
+            await this.fileSessions.dispose();
+        }
+        catch {
+        }
         this.fileCheckpoints.close();
         try {
             await this.fileMemory.flushEmbeds();

package/dist/stores/file/session-store.d.ts

@@ -2,10 +2,12 @@ import type { Session, SessionMetadata, SessionRepo, SessionTreeEntry } from "..
 export declare class FileSessionRepo implements SessionRepo {
     private readonly dir;
     private readonly tmpDir;
+    private readonly joined;
     constructor(root: string);
     private pathFor;
     private read;
     private storage;
+    dispose(): Promise<void>;
     create(options?: {
         id?: string;
     }): Promise<Session>;

package/dist/stores/file/session-store.js

@@ -20,11 +20,19 @@ function evictSharedSessionStorage(canonical) {
 class FileSessionStorage extends BaseSessionStorage {
     log;
     canonicalPath;
+    holders = new Set();
     constructor(log, meta, entries, canonicalPath) {
         super(meta, entries);
         this.log = log;
         this.canonicalPath = canonicalPath;
     }
+    addHolder(holder) {
+        this.holders.add(holder);
+    }
+    removeHolder(holder) {
+        this.holders.delete(holder);
+        return this.holders.size === 0;
+    }
     closeLog() {
         this.log.close();
     }
@@ -46,6 +54,7 @@ class FileSessionStorage extends BaseSessionStorage {
 export class FileSessionRepo {
     dir;
     tmpDir;
+    joined = new Map();
     constructor(root) {
         this.dir = join(root, "sessions");
         this.tmpDir = join(root, "tmp");
@@ -77,19 +86,37 @@ export class FileSessionRepo {
     storage(id, createdAt, entries, forkedFrom) {
         const canonical = canonicalStoreKey(this.pathFor(id));
         const live = sharedSessionStorages.get(canonical)?.deref();
-        if (live !== undefined)
+        if (live !== undefined) {
+            live.addHolder(this);
+            this.joined.set(canonical, new WeakRef(live));
             return live;
+        }
         const log = new AppendLog(this.pathFor(id));
         const created = new FileSessionStorage(log, { id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}) }, entries, canonical);
         sharedSessionStorages.set(canonical, new WeakRef(created));
+        created.addHolder(this);
+        this.joined.set(canonical, new WeakRef(created));
         sessionStorageFinalizer.register(created, { canonical, log }, created);
         return created;
     }
+    async dispose() {
+        for (const [canonical, ref] of this.joined) {
+            const mine = ref.deref();
+            if (mine === undefined)
+                continue;
+            if (sharedSessionStorages.get(canonical)?.deref() !== mine)
+                continue;
+            if (mine.removeHolder(this))
+                evictSharedSessionStorage(canonical);
+        }
+        this.joined.clear();
+    }
     async create(options = {}) {
         const id = options.id ?? uuidv7();
         const createdAt = new Date().toISOString();
         const path = this.pathFor(id);
         if (!existsSync(path)) {
+            evictSharedSessionStorage(canonicalStoreKey(path));
             atomicWriteFile(this.tmpDir, path, `${JSON.stringify({ kind: "meta", id, createdAt })}\n`);
             return new StoredSession(this.storage(id, createdAt, []));
         }

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -14,6 +14,7 @@ export interface CompoundReadonlyVerdict {
     reason?: string;
     outOfRootRead?: true;
     outOfRootPaths?: readonly string[];
+    checkedPaths?: readonly string[];
 }
 export declare function formatOutOfRootReadApprovalOption(directory: string): string;
 export declare function classifyCompoundReadonlyDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): CompoundReadonlyVerdict;

package/dist/tools/fs/bash-readonly-classifier.js

@@ -179,6 +179,7 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
     const args = tokens.folded.slice(1);
     const findings = [];
     const candidates = [];
+    const bareWordOperands = [];
     for (const rawArg of tokens.raw.slice(1)) {
         if (!hasUnquotedExpansionMetachar(rawArg))
             continue;
@@ -227,6 +228,8 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
                 continue;
             if (isPathShapedToken(t))
                 candidates.push(t);
+            else
+                bareWordOperands.push(t);
         }
     }
     for (const candidate of candidates) {
@@ -238,9 +241,16 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
             });
             continue;
         }
-        if (!withinAnyRoot(boundary.roots, resolved))
+        if (withinAnyRoot(boundary.roots, resolved))
+            findings.push({ kind: "inside", path: resolved });
+        else
             findings.push({ kind: "outside", command: name, path: resolved });
     }
+    for (const operand of bareWordOperands) {
+        const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], operand, boundary.homeDir);
+        if (resolved !== undefined && withinAnyRoot(boundary.roots, resolved))
+            findings.push({ kind: "inside", path: resolved });
+    }
     return findings;
 }
 export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
@@ -383,22 +393,29 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
 }
 function evaluateReadBoundary(foldedSegments, boundary) {
     const outside = [];
+    const inside = [];
     for (const toks of foldedSegments) {
         for (const finding of collectSegmentBoundaryFindings(toks, boundary)) {
             if (finding.kind === "unresolvable")
                 return { reason: finding.reason };
+            if (finding.kind === "inside") {
+                if (!inside.includes(finding.path))
+                    inside.push(finding.path);
+                continue;
+            }
             if (!outside.some((o) => o.path === finding.path))
                 outside.push(finding);
         }
     }
     if (outside.length === 0)
-        return {};
+        return inside.length > 0 ? { checkedPaths: inside } : {};
     const paths = outside.map((o) => `"${o.path}"`).join(", ");
     const allowed = boundary.roots.length > 0 ? boundary.roots.join(", ") : "(none)";
     return {
         reason: `"${outside[0].command}" reads ${paths}, outside the allowed directories for this session: ${allowed} — not auto-allowed`,
         outOfRootRead: true,
         outOfRootPaths: outside.map((o) => o.path),
+        ...(inside.length > 0 ? { checkedPaths: inside } : {}),
     };
 }
 export function classifySimpleCommandReadBoundary(command, boundary) {

package/dist/tools/fs/fs-bash.d.ts

@@ -14,7 +14,7 @@ export interface ExecClampOption {
     }) => () => void;
 }
 export declare function bashExitOneInterpretation(command: string): string | undefined;
-export declare function canAutoBackground(command: string): boolean;
+export declare function canAutoBackground(command: string, depth?: number): boolean;
 export declare function createBashTool(env: ExecutionEnv, rootCanonical: string, coAuthor?: string | false, cwdRef?: CwdRef, taskOpts?: {
     taskRegistry?: TaskRegistry;
     taskOwner?: string;

package/dist/tools/fs/fs-bash.js

@@ -6,6 +6,7 @@ import { hasBackgroundShell } from "../../core/background-shell.js";
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
 import { imageMagicMatches, withinAnyRoot } from "./safety.js";
+import { isRemoteExecutionEnv } from "../../core/remote-env.js";
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, } from "./fs-shared.js";
 import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyCompoundReadonly, classifySimpleCommandReadBoundary, } from "./bash-readonly-classifier.js";
@@ -137,7 +138,26 @@ function commandBasename(token) {
     const idx = token.lastIndexOf("/");
     return idx === -1 ? token : token.slice(idx + 1);
 }
-export function canAutoBackground(command) {
+const COMMAND_STRING_SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh", "ash"]);
+function commandStringPayload(tokens) {
+    const word = commandBasename(tokens[0] ?? "");
+    if (word === "eval")
+        return tokens.slice(1).join(" ");
+    if (!COMMAND_STRING_SHELLS.has(word))
+        return undefined;
+    const flagIdx = tokens.findIndex((t, i) => i > 0 && /^-[A-Za-z]*c[A-Za-z]*$/.test(t));
+    return flagIdx === -1 ? undefined : tokens.slice(flagIdx + 1).join(" ");
+}
+function unquotePayload(payload) {
+    const s = payload.trim();
+    const ansiC = /^\$'([\s\S]*)'$/.exec(s);
+    if (ansiC)
+        return (ansiC[1] ?? "").replace(/\\n/g, "\n").replace(/\\t/g, "\t");
+    const quoted = /^(['"])([\s\S]*)\1$/.exec(s);
+    return quoted ? (quoted[2] ?? "") : s;
+}
+const AUTO_BACKGROUND_MAX_WRAPPER_DEPTH = 3;
+export function canAutoBackground(command, depth = 0) {
     const segments = command
         .split(/&&|\|\||;|\||\r?\n/)
         .map((s) => s.trim())
@@ -149,6 +169,9 @@ export function canAutoBackground(command) {
         const word = commandBasename(tokens[0] ?? "");
         if (word === "git")
             return false;
+        const payload = depth < AUTO_BACKGROUND_MAX_WRAPPER_DEPTH ? commandStringPayload(tokens) : undefined;
+        if (payload !== undefined && payload.trim() !== "" && !canAutoBackground(unquotePayload(payload), depth + 1))
+            return false;
         if (word === "xargs" && tokens.slice(1).some((t) => commandBasename(t) === "git"))
             return false;
     }
@@ -641,6 +664,60 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
         },
     });
 }
+function createCanonicalReadBoundary(env, readRoots) {
+    const lexicalOnly = isRemoteExecutionEnv(env);
+    let rootsOnce;
+    const canonicalRoots = async (signal) => {
+        rootsOnce ??= (async () => {
+            const out = [];
+            for (const r of readRoots) {
+                const c = await env.canonicalPath(r, signal);
+                out.push(c.ok ? c.value : r);
+            }
+            return out;
+        })();
+        return await rootsOnce;
+    };
+    const resolve = async (p, signal) => {
+        const parts = p.split(/[\\/]/);
+        const tail = [];
+        while (parts.length > 0) {
+            const canon = await env.canonicalPath(parts.join("/") || "/", signal);
+            if (canon.ok) {
+                return [canon.value.replace(/[\\/]+$/, ""), ...[...tail].reverse()].join("/");
+            }
+            tail.push(parts.pop());
+        }
+        return undefined;
+    };
+    return {
+        escapesAfterResolution: async (paths, signal) => {
+            if (lexicalOnly || paths.length === 0)
+                return [];
+            const roots = await canonicalRoots(signal);
+            const escaping = [];
+            for (const p of paths) {
+                const real = await resolve(p, signal);
+                if (real === undefined)
+                    continue;
+                if (!withinAnyRoot(roots, real) && !escaping.includes(real))
+                    escaping.push(real);
+            }
+            return escaping;
+        },
+        allResolveInside: async (paths, signal) => {
+            if (lexicalOnly || paths.length === 0)
+                return false;
+            const roots = await canonicalRoots(signal);
+            for (const p of paths) {
+                const real = await resolve(p, signal);
+                if (real === undefined || !withinAnyRoot(roots, real))
+                    return false;
+            }
+            return true;
+        },
+    };
+}
 export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, opts) {
     const timeoutCaps = resolveBashTimeoutCaps(opts);
     const timeoutCapsSecView = bashTimeoutCapsSec(timeoutCaps);
@@ -659,14 +736,16 @@ export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, opt
         }
         return true;
     };
+    const canonicalBoundary = createCanonicalReadBoundary(env, readRoots);
     return defineTool({
         name: "Bash",
         contract: { contractId: "core.bash_readonly@1", implementationRevision: "1" },
         description: `Run a SINGLE read-only inspection command (e.g. ${sample}, …) and return its output. Shell ` +
             "operators (pipes, redirects, ;, &&, command substitution, subshells) are rejected and only " +
             "allowlisted commands run. Reads are confined to the workspace root(s): a path outside them is " +
-            "refused, as is one that cannot be resolved statically (e.g. a `~` path). Still subject to the " +
-            "deployment's approval policy.",
+            "refused, as is one that cannot be resolved statically (e.g. a `~` path). " +
+            (isRemoteExecutionEnv(env) ? "" : "A path that leads outside via a symlink counts as outside. ") +
+            "Still subject to the deployment's approval policy.",
         parameters: Type.Object({
             command: Type.String({ description: "A single allowlisted read-only command (no shell operators)." }),
             timeout: Type.Optional(Type.Number({ description: `Timeout in milliseconds (default ${timeoutCaps.defaultMs}, max ${timeoutCaps.maxMs}; requests above the max are capped to it).` })),
@@ -678,8 +757,17 @@ export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, opt
             if (reason)
                 return errorResult(`Error (Bash): ${reason}`);
             const boundary = classifySimpleCommandReadBoundary(command, { roots: readRoots, cwd: rootCanonical });
-            if (boundary.reason !== undefined && !(await readsOnlyEngineOverflowSpool(boundary))) {
-                return errorResult(`Error (Bash): ${boundary.reason}. bash_readonly is confined to the workspace roots; it has no approval path, so the call is refused rather than escalated.`, { code: "readonly_out_of_root", paths: boundary.outOfRootPaths ?? [] });
+            if (boundary.reason !== undefined) {
+                const rescued = boundary.outOfRootRead === true && (await canonicalBoundary.allResolveInside(boundary.outOfRootPaths ?? [], ctx.signal));
+                if (!rescued && !(await readsOnlyEngineOverflowSpool(boundary))) {
+                    return errorResult(`Error (Bash): ${boundary.reason}. bash_readonly is confined to the workspace roots; it has no approval path, so the call is refused rather than escalated.`, { code: "readonly_out_of_root", paths: boundary.outOfRootPaths ?? [] });
+                }
+            }
+            const escaping = await canonicalBoundary.escapesAfterResolution(boundary.checkedPaths ?? [], ctx.signal);
+            if (escaping.length > 0) {
+                const quoted = escaping.map((p) => `"${p}"`).join(", ");
+                return errorResult(`Error (Bash): a path this command reads resolves through a symlink to ${quoted}, outside the allowed directories for this session: ${readRoots.join(", ")} — not auto-allowed. ` +
+                    "bash_readonly is confined to the workspace roots; it has no approval path, so the call is refused rather than escalated.", { code: "readonly_out_of_root", paths: escaping });
             }
             return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, execClamp, ctx.toolCallId, true);
         },

package/dist/tools/loop-tick.js

@@ -49,7 +49,7 @@ Read and analyze freely — understanding the state of things has no blast radiu
 `;
 const DYNAMIC_APPENDIX = `
 
-If a Monitor is armed (check TaskList), keep \`delaySeconds\` at 1200–1800s — the Monitor is the wake signal and this is only the fallback heartbeat. If you were woken by a \`<task-notification>\`, handle the event before deciding whether to re-arm. To stop the loop, call ${SCHEDULE_WAKEUP_TOOL_NAME} with \`stop: true\` and TaskStop the monitor (use TaskList to find its task ID if no longer in context).`;
+If a Monitor is armed (its task_id was reported in the receipt when you started it), keep \`delaySeconds\` at 1200–1800s — the Monitor is the wake signal and this is only the fallback heartbeat. If you were woken by a \`<task-notification>\`, handle the event before deciding whether to re-arm. To stop the loop, call ${SCHEDULE_WAKEUP_TOOL_NAME} with \`stop: true\` and TaskStop the monitor (its task id is in that start receipt, and in the \`<task-id>\` of every notification the watch sends).`;
 function pushNotificationAppendix(persistentVariant) {
     const r = persistentVariant
         ? "newly blocked on a decision you won't make alone, you're ending the loop"

package/dist/tools/monitor.js

@@ -29,6 +29,16 @@ const MONITOR_DESCRIPTION = "Run a shell command in the background and watch its
     '- Wrong: `until grep -q "BUILD SUCCEEDED" build.log; do sleep 5; done` — if the build fails, this never exits and you wait until the watch times out.\n' +
     '- Right: `until grep -qE "BUILD (SUCCEEDED|FAILED)" build.log; do sleep 5; done` — every terminal state exits.\n' +
     "Before arming, ask: *if this process crashed right now, would my filter emit anything?* If not, widen it.";
+function envBackgroundWallSec(caps, requestedSec) {
+    const positive = (v) => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined);
+    const cap = positive(caps.maxBgTimeoutSec);
+    const base = requestedSec ?? positive(caps.defaultBgTimeoutSec);
+    if (base === undefined)
+        return cap;
+    if (cap === undefined)
+        return base;
+    return Math.min(base, cap);
+}
 export function createMonitorTool(env, opts) {
     return defineTool({
         name: "Monitor",
@@ -56,9 +66,10 @@ export function createMonitorTool(env, opts) {
             }
             const isPersistent = persistent === true;
             const timeoutMs = Math.min(MONITOR_MAX_TIMEOUT_MS, Math.max(1, Math.floor(timeout_ms ?? MONITOR_DEFAULT_TIMEOUT_MS)));
+            const spawnTimeoutSec = isPersistent ? undefined : Math.ceil(timeoutMs / 1000) + 5;
             const spawn = await env.spawnBackground(command, {
                 ...(opts.cwdRef !== undefined ? { cwd: opts.cwdRef.current } : {}),
-                ...(isPersistent ? {} : { timeout: Math.ceil(timeoutMs / 1000) + 5 }),
+                ...(spawnTimeoutSec !== undefined ? { timeout: spawnTimeoutSec } : {}),
             });
             if (!spawn.ok)
                 return errorResult(`Error (Monitor): ${spawn.error.message}`);
@@ -87,18 +98,50 @@ export function createMonitorTool(env, opts) {
                 });
             }
             catch (e) {
-                await env.killBackground(spawn.value.shellId).catch(() => undefined);
-                return errorResult(`Error (Monitor): the watch process was started but could not be registered (${e instanceof Error ? e.message : String(e)}); it has been terminated.`);
+                const why = e instanceof Error ? e.message : String(e);
+                let killDetail;
+                try {
+                    const kill = await env.killBackground(spawn.value.shellId);
+                    if (!kill.ok)
+                        killDetail = `${kill.error.code}: ${kill.error.message}`;
+                }
+                catch (killErr) {
+                    killDetail = killErr instanceof Error ? killErr.message : String(killErr);
+                }
+                return errorResult(killDetail === undefined
+                    ? `Error (Monitor): the watch process was started but could not be registered (${why}); it has been terminated.`
+                    : `Error (Monitor): the watch process was started but could not be registered (${why}), and it could NOT be terminated either (${killDetail}). ` +
+                        `It may still be running as background shell ${spawn.value.shellId}; no task id was minted, so TaskOutput/TaskStop cannot reach it — ` +
+                        "stop it out of band (the environment's own background time budget and its teardown sweep are the remaining backstops).");
             }
-            const bgTimeout = env.backgroundCapabilities.defaultBgTimeoutSec;
+            const bgTimeout = envBackgroundWallSec(env.backgroundCapabilities, spawnTimeoutSec);
             const wasClamped = timeout_ms !== undefined && timeout_ms !== timeoutMs;
             const clampNote = !isPersistent && wasClamped ? ` (clamped to ${timeoutMs}ms from your requested ${timeout_ms}ms)` : "";
             const timeoutIgnoredNote = isPersistent && timeout_ms !== undefined ? ` (the timeout_ms you passed is ignored because persistent is true)` : "";
+            const envWallMs = bgTimeout !== undefined ? bgTimeout * 1000 : undefined;
+            const envWallWins = !isPersistent && envWallMs !== undefined && envWallMs < timeoutMs;
+            const persistentBudget = bgTimeout !== undefined
+                ? `the execution environment kills background processes after ${bgTimeout}s`
+                : `the execution environment's background time budget still applies`;
+            const retainedByEnv = env.backgroundCapabilities.retainBackgroundProcesses === true;
+            const persistentAnchor = sessionScoped
+                ? retainedByEnv
+                    ? ". This environment declares retained background processes, so at the run teardown the watch is marked retained and " +
+                        "survives the session's release: only your TaskStop, the command's own exit, or that budget end it."
+                    : "; it runs until then, until you stop it, or until the session ends."
+                : retainedByEnv
+                    ? ". This mount carries no session identity, so the watch is NOT session-resident despite persistent: true; and because this " +
+                        "environment declares retained background processes it survives the session's release rather than being settled with the run — " +
+                        "nothing but your TaskStop, the command's own exit, or that budget will end it, and no later turn can reach it " +
+                        "(stop it explicitly with TaskStop before you finish)."
+                    : ". This mount carries no session identity, so the watch is NOT session-resident despite persistent: true — " +
+                        "it belongs to this task alone and the run teardown settles it, so do not count on it outliving this turn " +
+                        "(stop it explicitly with TaskStop when you are done).";
             const lifetime = isPersistent
-                ? typeof bgTimeout === "number"
-                    ? `It is persistent: no watch timeout of its own${timeoutIgnoredNote}, but the execution environment kills background processes after ${bgTimeout}s; it runs until then, until you stop it, or until the session ends.`
-                    : `It is persistent: no watch timeout of its own${timeoutIgnoredNote}, but the execution environment's background time budget still applies; it runs until then, until you stop it, or until the session ends.`
-                : `It will be killed after ${timeoutMs}ms${clampNote} if still running.`;
+                ? `It is persistent: no watch timeout of its own${timeoutIgnoredNote}, but ${persistentBudget}${persistentAnchor}`
+                : envWallWins
+                    ? `It will be killed after ${envWallMs}ms if still running — the execution environment's background time budget (${bgTimeout}s) is shorter than the ${timeoutMs}ms watch timeout${clampNote}, and the shorter of the two wins.`
+                    : `It will be killed after ${timeoutMs}ms${clampNote} if still running.`;
             const content = onNotify !== undefined
                 ? `Monitoring in background; task_id=${taskId}. Each stdout line becomes a notification event (lines within ` +
                     `~200ms are batched); you'll get a final notification with the exit code when it ends — do not poll. ` +
@@ -111,8 +154,11 @@ export function createMonitorTool(env, opts) {
                     type: "monitor-start",
                     taskId,
                     persistent: isPersistent,
+                    ...(bgTimeout !== undefined ? { envBudgetSec: bgTimeout } : {}),
+                    ...(envWallWins && envWallMs !== undefined ? { effectiveTimeoutMs: envWallMs } : {}),
                     ...(isPersistent
-                        ? { timeoutIgnored: timeout_ms !== undefined }
+                        ?
+                            { timeoutIgnored: timeout_ms !== undefined, sessionScoped, ...(retainedByEnv ? { retainedByEnv: true } : {}) }
                         : { timeoutMs, ...(timeout_ms !== undefined ? { requestedTimeoutMs: timeout_ms } : {}), wasClamped }),
                 },
             };

package/dist/tools/worktree.d.ts

@@ -8,6 +8,8 @@ export interface ActiveWorktreeSession {
 }
 export interface WorktreeSessionRef {
     current?: ActiveWorktreeSession;
+    exiting?: boolean;
+    entering?: boolean;
 }
 export interface WorktreeToolsOptions {
     repoRoot: string;