@sema-agent/server 1.322.0 → 2.0.0

package/dist/run-local.js

@@ -1,4 +1,26 @@
 #!/usr/bin/env node
+/**
+ * `run-local` — a ONE-SHOT local CLI for the agent engine.
+ *
+ * Boots the SAME runtime as `src/main.ts` (createBrain + Runner + the scenario/skills capability layer +
+ * the host execution env) IN-PROCESS, runs ONE task from the CLI objective to completion, prints the
+ * TaskResult, and exits. There is NO long-running HTTP server and NO submission auth gate — this is the
+ * whole point: it removes two friction points (the SERVICE_AUTH_TOKEN 503 on submit and the
+ * manual server lifecycle). The user fills `~/.ai-agent/.env` + `config.d/` (the LOCAL config source) and
+ * just runs `run-local "<objective>"`.
+ *
+ * Posture: LOCAL config mode (CONFIG_PROVIDER=local) → createConfigProvider → LocalConfigProvider →
+ * applyEffective (config.d/.env drives models/roles/mcp), and the `host` exec lane (run on THIS machine,
+ * no container) — identical building blocks to the server path so behavior matches (no drift). It reuses
+ * main.ts's helpers verbatim; the only thing it skips is the server-only surface (createHttpServer, listen,
+ * auth/rateLimit/quota/run-store/leader/durable-checkpoint/reapers).
+ *
+ *   Usage:  run-local "<objective>"  [--root <dir>] [--json] [--scenario <name>]
+ *
+ * `main()` is a thin wrapper over the testable {@link runLocal}, which takes argv + injectable
+ * deps (a mock Brain, a captured logger/printer, and an `exit` shim) so the assembly + one-shot flow can be
+ * exercised deterministically with no real LLM / network / keys.
+ */
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { realpathSync } from "node:fs";
@@ -24,6 +46,7 @@ import { buildPricing } from "./budget.js";
 import { createKeyResolver } from "./key-resolver.js";
 import { createLogger } from "./observability/logger.js";
 import { createMetrics } from "./observability/metrics.js";
+/** Parse argv (everything AFTER `node run-local.js`). Throws a clear Error on a missing objective. */
 export function parseArgs(argv) {
     let objective;
     let root;
@@ -34,6 +57,11 @@ export function parseArgs(argv) {
     let json = false;
     const valueFlag = (i, name) => {
         const v = argv[i];
+        // 空串/纯空白 = **没给参数**,不是"用户就想要空"(core [1689] 第 3 条同款:`??` 兜不住 `""`)。
+        // 收下它会让空串变成**隔离键**:`--session ""` → `args.session ?? uuidv7()` 得到 `""`,所有这类调用
+        // 复用同一个空 id「会话」;`--user ""` → `args.user ?? "local"` 得到 `""`,长期记忆落进匿名桶而不是
+        // 文档写的默认身份,且「传空串」与「不传」成为两个不同的桶。在解析器这一层拒才对 —— 这个函数存在的
+        // 意义本就是「这个 flag 需要一个参数」。
         if (v === undefined || v.trim() === "" || v.startsWith("--"))
             throw new UsageError(`${name} needs an argument`);
         return v;
@@ -59,7 +87,7 @@ export function parseArgs(argv) {
             throw new UsageError(`unknown flag: ${a}`);
         }
         else if (objective === undefined) {
-            objective = a;
+            objective = a; // first positional = the objective
         }
         else {
             throw new UsageError(`unexpected extra argument: ${a} (quote the objective as one argument)`);
@@ -70,15 +98,35 @@ export function parseArgs(argv) {
     }
     return { objective, root, json, ...(scenario ? { scenario } : {}), ...(session ? { session } : {}), ...(workspace ? { workspace } : {}), ...(user ? { user } : {}) };
 }
+/** A bad-usage error → print to stderr + exit 2 (distinct from a task failure exit 1). */
 export class UsageError extends Error {
 }
+/**
+ * The model GATEWAY pre-flight (mirrors the doctor message): the engine cannot run a real
+ * task without (a) a gateway base URL that ends in `/v1` and (b) the gateway/model API key resolvable from
+ * env. We surface a "you still need to set: …" list rather than letting the first brain call crash with a
+ * cryptic auth/connect error. Returns a list of missing items (empty = OK).
+ *
+ * NOTE: with an injected mock `brain` the gateway is irrelevant (no real call is made), so the caller skips
+ * this check in that case — the check is about a REAL run, not the assembly.
+ */
 export function missingGatewayRequirements(config) {
     const missing = [];
+    // (a) base URL: loadConfig always has a default, but a real local user must point it at THEIR gateway and
+    //     it must carry the OpenAI-compatible `/v1` suffix (the brain appends `/chat/completions`).
     if (!config.gatewayBaseUrl || !/\/v1\/?$/.test(config.gatewayBaseUrl)) {
         missing.push("MODEL_GATEWAY_BASEURL (the OpenAI-compatible gateway URL, must end in /v1)");
     }
+    // (b) the key: either the single gateway key (MODEL_API_KEY) OR — when the catalog pins a per-model
+    //     apiKeyEnv (sema-registry / config.d) — that named env var must be present. A model without its own
+    //     apiKeyEnv falls back to the gateway key, so the gateway key is the floor.
     const perModelEnvs = Object.values(config.modelApiKeyEnv ?? {});
     const haveGatewayKey = !!config.gatewayApiKey;
+    // The gateway key is the FLOOR: per-model keys only WAIVE it when EVERY catalog model the resolver may be
+    // asked about carries (and has set) its own apiKeyEnv. A model with no per-model key falls back to the
+    // gateway key, so a MIXED catalog (some models keyed, some not) with the gateway key unset would crash on
+    // the unkeyed model's first brain call. We dedupe via the model objects' `.name` so the synthetic `default`
+    // / model-id ALIAS entries of config.models (which mirror an existing per-name model) are not over-counted.
     const catalogModelNames = new Set(Object.values(config.models ?? {}).map((m) => m.name));
     const allModelsHaveOwnKey = catalogModelNames.size > 0 &&
         [...catalogModelNames].every((n) => {
@@ -97,6 +145,11 @@ export function missingGatewayRequirements(config) {
     }
     return missing;
 }
+/**
+ * Boot the engine in LOCAL mode, run ONE task to completion, print the result. Returns the process exit
+ * code (0 = completed, 1 = the task did not complete / a fatal error, 2 = bad usage / unmet env). Pure of
+ * `process.exit` so a test can assert the code; `main()` applies it.
+ */
 export async function runLocal(argv, deps = {}) {
     const print = deps.print ?? ((l) => console.log(l));
     const printErr = deps.printErr ?? ((l) => console.error(l));
@@ -111,17 +164,39 @@ export async function runLocal(argv, deps = {}) {
         }
         throw err;
     }
+    // FORCE local posture: a one-shot CLI is a single-machine run. Set the knob BEFORE loadConfig so
+    // (1) createConfigProvider selects the LocalConfigProvider and (2) config.ts defaults the `host` exec lane
+    // (the TOC first-run default for CONFIG_PROVIDER=local with no explicit REMOTE_EXEC). Honor an operator who
+    // already set it to something else (don't override an explicit choice) — but never leave it remote-by-default.
     if (!process.env.CONFIG_PROVIDER)
         process.env.CONFIG_PROVIDER = "local";
+    // FORCE the durable backends OFF: a one-shot, single-machine CLI has nothing durable to persist
+    // and deliberately does NOT assemble the server-only StoreBackend. A shared .env that carries
+    // SESSION_BACKEND=tidb would otherwise make loadConfig() (needsTidb → TIDB_HOST) or createSessionStore()
+    // throw a cryptic error before the run even starts. Unlike CONFIG_PROVIDER/REMOTE_EXEC (where an explicit
+    // operator choice can be HONORED), a DB session store cannot work here at all, so we FORCE — never honor —
+    // this knob to in-memory so the CLI just works regardless of the shared config. Long-term memory needs no
+    // forcing: the design/138 memory ENGINE is file-based and default-ON here (single-user; MEMORY_ENGINE=off
+    // and MEMORY_ENGINE_DIR pass through loadConfig as-is).
     process.env.SESSION_BACKEND = "memory";
+    // 🔴 REQUIRE_PRINCIPAL is the same shared-config footgun class: run-local IS the single
+    // user at their own terminal — there is no untrusted caller to gate — but a server .env carrying
+    // REQUIRE_PRINCIPAL=true would flip `memoryEngineBackendFor`/`memoryScopeFor` into the multi-tenant
+    // memory-dark branch (plus the host-power gates), silently killing the CLI's long-term memory. FORCE it off.
     process.env.REQUIRE_PRINCIPAL = "false";
+    // --root wins, then the standard local roots (mirrors main.ts's local-root resolution).
     const root = args.root ?? process.env.CONFIG_LOCAL_DIR ?? process.env.AGENT_DATA_DIR ?? join(homedir(), ".ai-agent");
     if (args.root)
-        process.env.CONFIG_LOCAL_DIR = args.root;
+        process.env.CONFIG_LOCAL_DIR = args.root; // so loadConfig's local-dir + the provider agree
     const config = loadConfig();
     const logger = deps.logger ?? createLogger(config.logLevel);
     const metrics = createMetrics();
+    // F10 (codex audit): run-local used to drop the pre-logger config diagnostics on the floor (S20 soft-knob
+    // warnings + [792]④ boot notices) — main.ts drained them, this entrypoint didn't. Shared helper, no drift.
     logConfigDiagnostics(logger);
+    // ── Config source (DUAL-MODE §4): resolve the effective config from the LOCAL FileConfigStore and apply it
+    //    OVER the env defaults (config.d/.env drives models/roles). Unreachable/empty → keep the env-derived
+    //    config (the local root may not exist yet — "fill .env and run" still works off env). ──
     const configProvider = createConfigProvider({
         provider: config.configProvider ?? "local",
         ...(config.configLocalDir ? { localDir: config.configLocalDir } : { localDir: root }),
@@ -130,10 +205,14 @@ export async function runLocal(argv, deps = {}) {
     try {
         const r = await configProvider.fetchEffective(undefined);
         if (r) {
+            // [898] tolerant read(registry-core 0.10.12):catalog 域坏文件不再连坐整包回落 env——坏域按 default
+            // 落+这里 per-domain warn 点名(文件路径在 error 文案里),好域照常生效。gate 域坏仍走下面整包 catch。
             for (const de of r.domainErrors ?? [])
                 logger.warn("config_domain_invalid", { domain: de.domain, error: de.error, note: "domain fell to schema defaults; other domains applied normally" });
             effective = r.effective;
             applyEffective(config, r.effective, logger);
+            // MCP servers (config.d/mcp.json or center) — applied here (NOT inside applyEffective, which only
+            // covers models/roles/gates/teams) so run-local matches the server path (main.ts:446). Restart-to-apply.
             if (effective?.mcp)
                 config.mcpServers = resolveMcpServers(effective.mcp, logger);
             logger.info("config_loaded", { source: configProvider.kind, version: r.effective.version });
@@ -142,6 +221,10 @@ export async function runLocal(argv, deps = {}) {
     catch (err) {
         logger.warn("config_source_unreachable_using_env", { source: configProvider.kind, err: String(err) });
     }
+    // ── remoteExec (DUAL-MODE §5): in local mode, honor the SHARED config.d/remote-exec.json via the registry
+    //    loader (the SAME file the client's `agent-cli config` writes). MISSING → keep config.ts's host default;
+    //    PRESENT host → it wins (workdir→workspaceBase); corrupt → fail-closed. Mirrors main.ts's block; the
+    //    isolated lanes (e2b/k8s/ssh/adb) stay env-sourced (a one-shot CLI is the host lane by design). ──
     try {
         const fileRx = await loadRemoteExec(root);
         if (fileRx?.provider === "host") {
@@ -161,6 +244,8 @@ export async function runLocal(argv, deps = {}) {
         printErr(`config.d/remote-exec.json is invalid: ${String(err)}`);
         return 2;
     }
+    // ── Pre-flight: with a REAL brain, validate the gateway + key and print the doctor-style guidance instead
+    //    of crashing on the first brain call. With an injected mock brain, no real call happens → skip. ──
     if (!deps.brain) {
         const missing = missingGatewayRequirements(config);
         if (missing.length > 0) {
@@ -171,8 +256,12 @@ export async function runLocal(argv, deps = {}) {
             return 2;
         }
     }
+    // ── Minimal runtime assembly (the SAME building blocks as main.ts, server-only bits omitted). ──
     const brain = deps.brain ?? createBrain(config, deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {});
     const pricing = buildPricing(config.models);
+    // Persistent LOCAL stores (TOC): core's file-backed StorageBackend under the data root → session + long-term
+    // memory + checkpoints SURVIVE across invocations (no DB). flock'd single-instance per data dir; a second
+    // concurrent instance throws in the constructor — surface a clear message instead of a stack.
     let fileBackend;
     try {
         fileBackend = new FileStorageBackend({ root });
@@ -184,17 +273,36 @@ export async function runLocal(argv, deps = {}) {
     }
     const sessionStore = fileBackend.sessionStore;
     const keyResolver = createKeyResolver(config.modelApiKeyEnv);
+    // Host exec lane: run on THIS machine, in a FIXED workspace (CC-like) — the cwd by default (or --workspace /
+    // a config.d workdir). The agent's file edits PERSIST there + are user-visible; the dir is the user's OWN and
+    // is NEVER deleted (workspaceDir mode). One env per task; the Runner owns its lifetime.
     const hostRx = config.remoteExec?.provider === "host" ? config.remoteExec : undefined;
     const workspaceDir = args.workspace ?? hostRx?.workspaceBase ?? process.cwd();
     const executionEnvFactory = hostRx
         ? hostExecutionEnvFactory({
             workspaceDir,
+            // systematic-audit (uniformity with main.ts:442 + the worktree-lane gates): gate background-shell by tenancy.
+            // run-local is a single-user CLI (no untrusted caller) so requirePrincipal is ~always false → ON; passing the
+            // gate keeps the policy uniform if a shared .env ever sets REQUIRE_PRINCIPAL, never relying on the `?? true`.
             backgroundShell: config.requirePrincipal !== true,
             ...(hostRx.commandTimeoutMs != null ? { commandTimeoutMs: hostRx.commandTimeoutMs } : {}),
         })
         : undefined;
+    // TOC local LSP (core 1.190): run-local IS the pure-local host lane, so mount core's `NodeLspManager` (local
+    // child_process language servers over stdio, CC `services/lsp` parity) on the host lane. Default ON (degrades
+    // gracefully to grep/read if a server binary is absent); `LSP_HOST_ENABLED=false` opts out (design/158 B4 split
+    // this lane off `LSP_ENABLED`, which still works as a back-compat opt-out). `requirePrincipal !== true`
+    // keeps it uniform with main.ts (a no-op here — run-local is single-user — but never relies on that). Both runners.
     const lspManager = hostRx && config.lspHostEnabled && config.requirePrincipal !== true ? new NodeLspManager({ log: (event, fields) => logger.info(event, fields) }) : undefined;
+    // Long-term memory (design/138 S1): run-local IS the single-user lane, so the file-based memory ENGINE is
+    // default-ON (MEMORY_ENGINE=off opts out). The data root doubles as the engine config-root fallback so a
+    // run-local and the local HTTP service on one box share ONE memory home (MEMORY_ENGINE_DIR overrides).
     const memoryEngine = memoryEngineBackendFor(config, root);
+    // 142-S2.5-W1: TOC 同步 client 腿——run-local 是 file memory 形态本尊(loadConfig 已拒
+    // DB backend 上的 MEMORY_SYNC_*)。run-local 没接 onMemoryHarvestReport 钩子(一次性 CLI:harvest 只在
+    // 任务收尾发生一次,fire-and-forget 轮会被进程退出腰斩),按设计的后备姿势:boot fire-and-forget 一轮
+    // (拉中心增量,失败 warn 不阻断;进程退出腰斩也安全——cursor 保留纪律下轮重收敛)+ 任务结束后 await
+    // 一轮(推本次 harvest 的新记忆;syncOnce 串行链自动排在 boot 轮之后)。
     let memorySync;
     if (config.memorySync && memoryEngine) {
         memorySync = createMemorySyncRunner({
@@ -210,7 +318,12 @@ export async function runLocal(argv, deps = {}) {
     else if (config.memorySync) {
         logger.warn("memory_sync_configured_but_memory_dark", { note: "MEMORY_SYNC_URL is set but the file memory engine is dark (MEMORY_ENGINE=off / remote exec lane) — no sync rounds will run" });
     }
+    // codex-2 F3([985]e run-local 半场):config.d/prompts.json 的 catalog 轴在这条 lane 也要真消费——
+    // 判形(与 server 同一候选门)→ CenterPromptSource(File 形,<root>/prompt-epoch 自管)→ 两 Runner 的
+    // promptSource。坏形/apply 失败=warn + 内置照跑(单进程本地形,无 refresh 重试拍;下次启动再试)。
     const promptEpochDir = join(root, "prompt-epoch");
+    // codex-7:守护工厂与 main.ts 同姿势——File 店构造同步 mkdir,坏 prompt-epoch 路径不得把可选特性
+    // 变成 run-local 启动致命(Memory 兜底=candidate 不跨启动持久;内置照跑)。
     const promptSource = (() => {
         try {
             return new CenterPromptSource({
@@ -225,7 +338,7 @@ export async function runLocal(argv, deps = {}) {
         }
     })();
     try {
-        await promptSource.restore();
+        await promptSource.restore(); // run-local IS the owning local provider — the on-disk candidate is authoritative
         const promptsRaw = effective?.prompts;
         if (promptsRaw !== undefined) {
             const pv = validatePromptsDomain(promptsRaw);
@@ -235,6 +348,8 @@ export async function runLocal(argv, deps = {}) {
                 logger.warn("center_prompts_invalid", { phase: "run-local", error: pv.error, note: "malformed prompts face — built-ins serve" });
         }
         else {
+            // no prompts face on this boot: a persisted candidate whose file was removed must not survive (same
+            // cleared semantics as the server lane) — applyCatalogToSource's current() probe handles the owed disable.
             await applyCatalogToSource(promptSource, undefined, undefined, logger, "run-local");
         }
     }
@@ -247,35 +362,57 @@ export async function runLocal(argv, deps = {}) {
         roles: config.roles,
         pricing,
         promptSource,
+        // [931]① clay 拍:run-local=Sema 品牌本地形态,commit 尾注接 Sema 署名(core 1.300 缺省已翻转不署)。
         hands: { commitCoAuthor: "Sema <noreply@vivi-ai.com>" },
         sessionStore,
         ...(memoryEngine ? { memoryBackend: memoryEngine.backend, memoryEngineDir: memoryEngine.root } : {}),
         checkpointStore: fileBackend.checkpointStore,
+        // core 1.219 (dogfood: "ReadToolResult(ref) 恒空"): durable tool-result refs on the TOC CLI
+        // lane too — offloaded full text survives a process restart (one file per ref under the data root).
         toolResultStore: fileBackend.toolResultStore,
         ...(executionEnvFactory ? { executionEnvFactory } : {}),
         ...(lspManager ? { lspManager } : {}),
+        // design/113 C4: run-local IS the single-user host lane (cwd = --workspace ?? process.cwd()) — the CLI path where
+        // CLAUDE.md project-awareness most belongs. Wire it unless explicitly disabled.
         ...(config.projectMemoryEnabled
             ? { loadProjectMemory: makeLoadProjectMemory({ logger }), probeInstructionSources: makeProbeInstructionSources() }
             : {}),
     });
+    // Sub-task runner (council lenses/team) — mirrors main.ts's subRunner, INCLUDING executionEnvFactory so a delegated
+    // child gets hands (Bash/Read/Edit) on the host lane. Without it the child's handsEnabled is false — the exact
+    // "subagent couldn't run pwd" defect fixed at main.ts:799; this is its run-local twin, caught by the systematic audit.
+    // [1367]① fork server half(main.ts subRunner 同款):ForkRoutingSessionStore——fork/resume 形
+    // (requireExisting)→ host 文件店优先(core 1.350 hostSessionFork 在宿主店 fork,拆店=响亮
+    // resume.session_not_found),普通子任务 → 私有 TTL 店(throwaway 姿势保留)。
     const subRunner = new Runner({ brain, models: config.models, roles: config.roles, pricing, promptSource, sessionStore: new ForkRoutingSessionStore(sessionStore, new TtlSessionStore({ defaultTtlDays: 1 / 24 })), ...(executionEnvFactory ? { executionEnvFactory } : {}), ...(lspManager ? { lspManager } : {}) });
+    // Capability layer (loadSkills + buildScenarios + selectScenario) — assembled exactly like main.ts.
     const skills = loadSkills(config.skillsDir);
     const repoClient = config.gitApiBaseUrl ? new GiteaClient(config.gitApiBaseUrl, config.gitApiToken) : undefined;
+    // systematic-audit: wire the env-configured WebSearch backend (WEB_SEARCH_PROVIDER) exactly like main.ts, so the
+    // default scenario's WebSearch tool is assembled on the CLI path too (it was silently never built before).
     const webSearchCfg = webSearchConfigFromEnv();
     const webSearch = webSearchCfg ? createWebSearchBackend(webSearchCfg) : undefined;
     const scenarioDeps = {
         runner, subRunner, model: "default", skills, repoClient, metrics, logger,
         oaApiBaseUrl: config.oaApiBaseUrl, oaServiceToken: config.oaServiceToken, oaIssue: config.oaIssue,
         ...(webSearch ? { webSearch } : {}),
-        brandIdentity: true,
+        brandIdentity: true, // run-local is always a local/TOC deployment → brand the default scenario as Sema.
     };
     const scenarios = buildScenarios(scenarioDeps);
+    // Center-/config.d-declared scenarios (composition-as-config): overlay over the built-ins, center wins —
+    // mirrors main.ts:453-457 so a config.d/scenarios.json scenario resolves identically in run-local (no drift).
     if (effective?.scenarios) {
         const { overlay } = centerScenarios(scenarioDeps, effective.scenarios.scenarios, Object.keys(scenarios), logger);
         Object.assign(scenarios, overlay);
     }
+    // ── Build the TaskSpec the way the /v1/tasks sync handler's resolveSpec does (minus server-only fields:
+    //    no auth/principal/durable/approval/budget-cap-from-body). Fresh sessionId; @-model mention honored. ──
     const requested = args.scenario ?? config.defaultScenario;
     const scenarioName = scenarios[requested] ? requested : "default";
+    // A scenario may THROW HttpError synchronously when a prerequisite is unmet (e.g. `scan` needs
+    // GIT_API_BASEURL + a repo; `oa` needs OA_* + an authenticated principal — neither of which a one-shot CLI
+    // supplies). The server catches this in resolveSpec/prepareSpec and returns a clean 4xx; here we mirror that
+    // with the doctor-style UX (message to stderr + exit 2) instead of letting it bubble to the fatal exit-1 path.
     let cap;
     try {
         cap = selectScenario(scenarios, scenarioName)({ scenario: scenarioName, objective: args.objective });
@@ -285,34 +422,48 @@ export async function runLocal(argv, deps = {}) {
             printErr(`cannot run scenario "${scenarioName}": ${err.message}`);
             if (scenarioName === "scan")
                 printErr("(the `scan` scenario needs a git API base URL and a repo — run-local cannot supply a repo; use the default scenario)");
-            void lspManager?.dispose();
+            void lspManager?.dispose(); // symmetry (harmless no-op here — servers spawn lazily during runTask, not yet)
             await fileBackend.dispose();
             return 2;
         }
         throw err;
     }
     const mention = parseModelMention(args.objective, Object.keys(config.models));
+    // --session REUSES a session (durable multi-turn across invocations, via the file session store); absent →
+    // a fresh uuidv7 (still persisted). --user is the stable memory/identity scope so long-term memory
+    // accumulates per user (default "local" = the single TOC user). The file stores acquire/append lazily.
     const sessionId = args.session ?? uuidv7();
     const scope = args.user ?? "local";
+    // Timeout policy mirrors the server (taskWallClockSec): run-local IS the pure single-user
+    // TOC lane → NO wall clock by default (core's wedge safety-net still applies); explicit TASK_TIMEOUT_SEC
+    // wins with its raise-only floor (team 1500s — a multi-agent coordinator legitimately exceeds 600s).
+    // [854]④ 不落此腿:per-request body.limits 是 HTTP body 车道(resolveTaskLimits,main.ts resolveSpec);
+    // run-local 无 body,配速仍走 env(要 CLI flag 时另开件,别在这里半做)。
     const taskTimeoutSec = Math.max(0, Math.floor(Number(process.env.TASK_TIMEOUT_SEC ?? "0")) || 0);
     const timeoutSec = taskWallClockSec(taskTimeoutSec, false, scenarioName === "team");
     const mcp = mcpForScenario(config.mcpServers, scenarioName);
     const spec = {
         objective: mention.cleanedText || args.objective,
         sessionId,
+        // design/129: run-local IS the pure TOC lane → session-scoped background children
+        // (CC Backgrounded semantics; parity with the server's single-user posture).
         backgroundScope: "session",
-        principal: scope,
+        principal: scope, // stable local memory/identity scope (single-user TOC; --user overrides)
+        // design/138 S1: enable the memory engine for this run (spec.memory is core's per-task activation half of
+        // the deps.memoryBackend switch). Scope = the --user identity (default "local", the single TOC user).
         ...(memoryEngine ? { memory: memorySpecForRequest(scope, undefined) } : {}),
         model: mention.model ?? "default",
         getApiKeyAndHeaders: keyResolver,
         tools: cap.tools,
         skills: cap.skills,
         ...(cap.promptProvider ? { promptProvider: cap.promptProvider } : {}),
+        // [849] 场景层定死的终验(autonomous 场景)——与 main.ts resolveSpec 同语义,CLI 路径不漂移。
         ...(cap.finalVerification === true ? { finalVerification: true } : {}),
         ...(mcp ? { mcp } : {}),
         ...(timeoutSec !== undefined ? { limits: { timeoutSec } } : {}),
     };
     logger.info("run_local_start", { scenario: scenarioName, model: spec.model, sessionId, exec: config.remoteExec?.provider ?? "in-process" });
+    // ── Run ONE task to completion (the sync /v1/tasks path: plain runTask, no verify/cascade). ──
     let result;
     let exitCode = 0;
     try {
@@ -320,12 +471,14 @@ export async function runLocal(argv, deps = {}) {
     }
     catch (err) {
         printErr(`task crashed: ${err instanceof Error ? err.message : String(err)}`);
+        // Clean shutdown even on a crash.
         runner.sessions.dispose();
         subRunner.sessions.dispose();
-        void lspManager?.dispose();
+        void lspManager?.dispose(); // Kill local child-process language servers so a re-run doesn't orphan them
         await fileBackend.dispose();
         return 1;
     }
+    // ── Output: --json → the full TaskResult; else the final assistant text (or salvaged/blocked/error info). ──
     if (args.json) {
         print(JSON.stringify(result, null, 2));
     }
@@ -333,6 +486,7 @@ export async function runLocal(argv, deps = {}) {
         print(result.result);
     }
     else {
+        // Non-completed: surface the most useful text we have, then a one-line status footer to stderr.
         const salvage = result.result || result.salvagedOutput || result.blockedReason || "";
         if (salvage)
             print(salvage);
@@ -340,6 +494,9 @@ export async function runLocal(argv, deps = {}) {
     }
     if (result.status !== "completed")
         exitCode = 1;
+    // 142-S2.5-W1: 任务结束后 await 一轮同步(推本次 harvest 的新记忆到中心;串行链自动排在 boot 轮
+    // 之后,绝不并发互踩)。await 保证轮次在进程退出前完成(fire-and-forget 会被 exit 腰斩);失败只
+    // warn——同步是增益面,绝不改变任务本身的退出码。输出已打印完,这里的等待不挡用户看结果。
     if (memorySync) {
         try {
             await memorySync.syncOnce("post-task");
@@ -348,16 +505,23 @@ export async function runLocal(argv, deps = {}) {
             logger.warn("memory_sync_failed", { reason: "post-task", err: String(err) });
         }
     }
+    // ── Clean shutdown: dispose the warm sessions; the host env workspace is rm -rf'd by the Runner on task
+    //    end (executionEnvFactory env → destroy()). No server/pool/reaper to tear down (none were created). ──
     runner.sessions.dispose();
     subRunner.sessions.dispose();
-    void lspManager?.dispose();
+    void lspManager?.dispose(); // SAME as the crash path — kill local child-process language servers on the
+    // SUCCESS path too. `runLocal` is exported/reusable (tests/embeddings call it directly, no process.exit), so
+    // without this a completed LSP-touching run orphans a fresh set of stdio servers; the leak is per-invocation.
     await fileBackend.dispose();
     return exitCode;
 }
+/** Process entrypoint: run, print, exit with the resolved code. */
 async function main() {
     const code = await runLocal(process.argv.slice(2));
     process.exit(code);
 }
+// Only auto-run when invoked as a script (not when imported by the test). Compare REALPATH-resolved paths
+// so symlinked roots (/tmp→/private/tmp) and the tsx loader's file URL still match the entrypoint argv[1].
 function isMainModule() {
     const entry = process.argv[1];
     if (!entry)