chainlesschain 0.162.162 → 0.162.164

package/src/lib/sub-agent-context.js

@@ -45,8 +45,10 @@ export class SubAgentContext {
    * @param {number} [options.maxIterations] - Iteration limit (fallback if no budget)
    * @param {import('./iteration-budget.js').IterationBudget} [options.iterationBudget] - Shared iteration budget (takes priority over maxIterations)
    * @param {number} [options.tokenBudget] - Optional token budget
-   * @param {object} [options.db] - Database instance
+   * @param {object} [options.db] - Database instance (memory recall source)
    * @param {object} [options.permanentMemory] - Permanent memory instance
+   * @param {boolean} [options.memoryEnabled=true] - When false, the child's
+   *   context engine suppresses hierarchical-memory recall (contract memory:false)
    * @param {object} [options.llmOptions] - LLM provider/model/key options
    * @param {string} [options.cwd] - Working directory
    * @param {boolean} [options.useWorktree] - Force worktree isolation (overrides flag)
@@ -77,6 +79,14 @@ export class SubAgentContext {
     // Shared run-wide TOTAL-sub-agent counter (one object across the whole tree)
     // so this sub-agent's own spawns draw from the same breadth pool.
     this.subAgentBudget = options.subAgentBudget || null;
+    // This context's EFFECTIVE subagent contract — the ceiling handed to its OWN
+    // nested spawns (threaded into the loop options so a nested spawn_sub_agent
+    // reads it as ctx.subAgentContract).
+    this.subAgentContract = options.subAgentContract || null;
+    // Skill capability INTERSECT: null = unrestricted; a list (possibly empty)
+    // restricts run_skill/list_skills in this context's loop to those skills.
+    this.skillAllowlist =
+      options.skillAllowlist != null ? options.skillAllowlist : null;
     this.cwd = options.cwd || process.cwd();
     this.status = "active";
     this.result = null;
@@ -93,10 +103,17 @@ export class SubAgentContext {
     // Independent message history — never shared with parent
     this.messages = [];
 
-    // Independent context engine — does not inherit parent's compaction/errors
+    // Independent context engine — does not inherit parent's compaction/errors.
+    // Memory recall is gated by the subagent contract: the spawn passes a `db`
+    // and memoryEnabled:true only when the resolved contract grants memory
+    // (context:fork from a memory-bearing parent, or explicit memory:true).
+    // Default (silent-`fresh`→memory:false) → no db + memoryEnabled:false → no
+    // recall, which is today's byte-identical behavior for a plain sub-agent.
+    this._memoryEnabled = options.memoryEnabled !== false;
     this.contextEngine = new CLIContextEngineering({
       db: options.db || null,
       permanentMemory: options.permanentMemory || null,
+      memoryEnabled: this._memoryEnabled,
       scope: {
         taskId: this.id,
         role: this.role,
@@ -123,8 +140,13 @@ export class SubAgentContext {
     this._onUsage =
       typeof options.onUsage === "function" ? options.onUsage : null;
 
-    // Optional abort signal for cancellation
+    // Optional EXTERNAL abort signal for cancellation (e.g. a parent-provided
+    // AbortSignal). In addition, every context owns an INTERNAL controller so a
+    // single sub-agent can be cancelled precisely by id via `abort()` (the
+    // registry's `cancel(id)`), independent of any external signal.
     this._signal = options.signal || null;
+    this._abortController = new AbortController();
+    this._cancelReason = null;
 
     // Optional MCP / external tool plumbing. These are forwarded into the
     // agentLoop options so MCP-backed tools (e.g. from a cowork template's
@@ -145,6 +167,22 @@ export class SubAgentContext {
         : {};
     this._mcpClient = options.mcpClient || null;
 
+    // Inherited settings hooks (Pre/PostToolUse) for this child loop. null =
+    // no hooks (the spawn default). The spawn path passes the parent's hooks
+    // filtered by the contract's `hooks` allow-list; forwarded into agentLoop.
+    this._settingsHooks = options.settingsHooks || null;
+
+    // permissionMode confirmer for this child loop. null = no confirmer (the
+    // spawn default → the child denies ask/sensitive-file/git gates). The spawn
+    // sets this only for the autopilot (bypassPermissions) ALLOW confirmer.
+    this._permissionConfirm = options.permissionConfirm || null;
+
+    // permissionMode ApprovalGate for this child loop. null = ungated (the spawn
+    // default). The spawn sets a dedicated confirmer-less gate (seeded with the
+    // mode's tier) for the strict/trusted tiers so run_shell/browser_act are
+    // gated headlessly (CONFIRM→no-confirmer→DENY).
+    this._approvalGate = options.approvalGate || null;
+
     // Build isolated system prompt
     const basePrompt = buildSystemPrompt(this.cwd);
     const profilePrompt = this._profile?.systemPrompt
@@ -176,9 +214,25 @@ export class SubAgentContext {
       );
     }
 
-    // If worktree isolation is enabled, wrap execution in isolated worktree
-    if (this._useWorktree && isGitRepo(this._repoDir)) {
-      return this._runInWorktree(userPrompt, loopOptions);
+    // If worktree isolation is enabled, wrap execution in isolated worktree.
+    if (this._useWorktree) {
+      if (isGitRepo(this._repoDir)) {
+        return this._runInWorktree(userPrompt, loopOptions);
+      }
+      // FAIL CLOSED: isolation was explicitly requested but this is not a git
+      // repo. Never silently fall back to the parent checkout — refuse.
+      this.status = "failed";
+      this.completedAt = new Date().toISOString();
+      this.result = {
+        summary:
+          "Worktree isolation was requested but the working directory is not a git repository — refusing to run in the parent checkout.",
+        artifacts: [],
+        tokenCount: this._tokenCount,
+        toolsUsed: [...new Set(this._toolsUsed)],
+        iterationCount: this._iterationCount,
+        isolationError: true,
+      };
+      return this.result;
     }
 
     return this._runCore(userPrompt, loopOptions);
@@ -270,6 +324,10 @@ export class SubAgentContext {
       // Shared total-sub-agent counter so a nested spawn_sub_agent draws from
       // (and is bounded by) the run's single breadth pool.
       subAgentBudget: this.subAgentBudget,
+      // This context's effective contract = the ceiling for its nested spawns.
+      subAgentContract: this.subAgentContract,
+      // Skill allow-list restricting run_skill/list_skills in this loop.
+      skillAllowlist: this.skillAllowlist,
       ...loopOptions,
     };
     if (this.iterationBudget) {
@@ -298,6 +356,22 @@ export class SubAgentContext {
     if (this._mcpClient) {
       options.mcpClient = this._mcpClient;
     }
+    // Inherited Pre/PostToolUse hooks (spawn passes the parent's, filtered by
+    // the contract's `hooks` allow-list). Only set when non-null so a plain
+    // sub-agent keeps its no-hooks default.
+    if (this._settingsHooks) {
+      options.settingsHooks = this._settingsHooks;
+    }
+    // permissionMode confirmer (spawn sets it only for bypassPermissions). Only
+    // forward when present so a plain sub-agent keeps its implicit-deny default.
+    if (this._permissionConfirm) {
+      options.permissionConfirm = this._permissionConfirm;
+    }
+    // permissionMode ApprovalGate (spawn sets it for strict/trusted tiers). Only
+    // forward when present so a plain sub-agent stays ungated (byte-identical).
+    if (this._approvalGate) {
+      options.approvalGate = this._approvalGate;
+    }
 
     try {
       // Use a separate messages array for the agent loop
@@ -361,9 +435,9 @@ export class SubAgentContext {
           }
         }
 
-        // Check abort signal
-        if (this._signal?.aborted) {
-          this.forceComplete("cancelled", {
+        // Check abort signal (external OR this context's own `abort()`)
+        if (this.isAborted()) {
+          this.forceComplete(this._cancelReason || "cancelled", {
             partialContent: lastContent,
             artifacts,
           });
@@ -512,6 +586,33 @@ export class SubAgentContext {
     }
   }
 
+  /**
+   * True when this sub-agent has been asked to stop — either via an external
+   * abort signal or via this context's own `abort()` (precise single-agent
+   * cancel). The agent loop checks this each iteration and winds down
+   * cooperatively (force-completes with the partial work it has).
+   */
+  isAborted() {
+    return Boolean(
+      this._signal?.aborted || this._abortController.signal.aborted,
+    );
+  }
+
+  /**
+   * Precisely cancel THIS sub-agent: trip its internal abort signal so the loop
+   * stops at its next iteration and hands back partial work. Idempotent. The
+   * `reason` surfaces in the force-completed summary. Returns true if the abort
+   * was newly requested, false if it was already aborted / not active.
+   */
+  abort(reason = "cancelled") {
+    if (this.status !== "active" || this._abortController.signal.aborted) {
+      return false;
+    }
+    this._cancelReason = reason;
+    this._abortController.abort();
+    return true;
+  }
+
   /**
    * Get a serializable snapshot of this context (for debugging/logging).
    */

package/src/lib/sub-agent-registry.js

@@ -188,6 +188,25 @@ export class SubAgentRegistry {
     }
   }
 
+  /**
+   * Precisely cancel a SINGLE active sub-agent by id (the per-agent sibling of
+   * `forceCompleteAll`). Trips the context's abort signal so its loop stops at
+   * the next iteration and hands back partial work; the normal completion path
+   * then moves it to history. Cooperative — a loop blocked on a long call winds
+   * down at its next check.
+   *
+   * @param {string} id - Sub-agent id to cancel
+   * @param {string} [reason="cancelled"] - Surfaced in the force-completed summary
+   * @returns {{ found: boolean, cancelled: boolean }}
+   */
+  cancel(id, reason = "cancelled") {
+    const subCtx = this._active.get(id);
+    if (!subCtx) return { found: false, cancelled: false };
+    const cancelled =
+      typeof subCtx.abort === "function" ? subCtx.abort(reason) : false;
+    return { found: true, cancelled };
+  }
+
   /**
    * Clean up stale entries older than maxAgeMs.
    * @param {number} [maxAgeMs=600000] - Max age in ms (default: 10 minutes)

package/src/lib/subagent-inheritance.js

@@ -0,0 +1,112 @@
+/**
+ * Subagent capability INHERITANCE + INTERSECT (P1 §"补齐 Subagent 契约").
+ *
+ * A spawned sub-agent inherits the parent loop's MCP tools and Pre/PostToolUse
+ * hooks ONLY through these filters, keyed off the resolved contract's
+ * `mcpServers` / `hooks` allow-lists. The tri-state matches
+ * `resolveSubagentContract` (see subagent-contract.js):
+ *
+ *   allow === null   → inherit ALL (context:fork with an unrestricted parent)
+ *   allow === []     → inherit NONE (the silent-`fresh` default = today's
+ *                      behavior: a spawned child gets no MCP tools / no hooks)
+ *   allow === [...]  → inherit only the named servers / hook matchers
+ *
+ * Because the default is `[]` = none, wiring these is byte-identical for a
+ * plain sub-agent and only grants capabilities when the contract explicitly
+ * opts in (fork context or an explicit list). Pure — no I/O.
+ *
+ * @module subagent-inheritance
+ */
+
+/** Extract the server segment from an `mcp__<server>__<tool>` wire name. */
+export function mcpServerOf(name) {
+  const s = String(name || "");
+  if (!s.startsWith("mcp__")) return null;
+  const rest = s.slice(5);
+  const idx = rest.indexOf("__");
+  return idx === -1 ? rest || null : rest.slice(0, idx) || null;
+}
+
+/**
+ * Filter the parent's MCP plumbing to the servers the child may use.
+ *
+ * @param {object} parent  { extraToolDefinitions[], externalToolDescriptors{},
+ *                            externalToolExecutors{}, mcpClient }
+ * @param {string[]|null} allow  null=all, []=none, list=subset of server names
+ * @returns {object|null}  filtered plumbing, or null when nothing is inherited
+ */
+export function filterInheritedMcp(parent, allow) {
+  if (Array.isArray(allow) && allow.length === 0) return null; // none
+  const allowSet = Array.isArray(allow) ? new Set(allow) : null; // null = all
+  const serverAllowed = (server) =>
+    !allowSet || (server != null && allowSet.has(server));
+
+  const defs = Array.isArray(parent?.extraToolDefinitions)
+    ? parent.extraToolDefinitions
+    : [];
+  const descs =
+    parent?.externalToolDescriptors &&
+    typeof parent.externalToolDescriptors === "object"
+      ? parent.externalToolDescriptors
+      : {};
+  const execs =
+    parent?.externalToolExecutors &&
+    typeof parent.externalToolExecutors === "object"
+      ? parent.externalToolExecutors
+      : {};
+
+  const outDefs = defs.filter((d) => {
+    const name = d?.function?.name;
+    return name && serverAllowed(mcpServerOf(name));
+  });
+  const outDescs = {};
+  for (const [name, desc] of Object.entries(descs)) {
+    const server = desc?.serverName || mcpServerOf(name);
+    if (serverAllowed(server)) outDescs[name] = desc;
+  }
+  const outExecs = {};
+  for (const [name, exec] of Object.entries(execs)) {
+    const server = exec?.serverName || mcpServerOf(name);
+    if (serverAllowed(server)) outExecs[name] = exec;
+  }
+
+  if (
+    outDefs.length === 0 &&
+    Object.keys(outDescs).length === 0 &&
+    Object.keys(outExecs).length === 0
+  ) {
+    return null; // nothing survived the filter — inherit no MCP
+  }
+  return {
+    extraToolDefinitions: outDefs,
+    externalToolDescriptors: outDescs,
+    externalToolExecutors: outExecs,
+    mcpClient: parent?.mcpClient || null,
+  };
+}
+
+/**
+ * Filter the parent's settings hooks to the matchers the child may fire. Hooks
+ * have no name; a group's `matcher` (normalized: null/""→"*") is its identity.
+ *
+ * @param {object|null} settingsHooks  { [event]: [{matcher, hooks:[...]}] }
+ * @param {string[]|null} allow  null=all, []=none, list=subset of matchers
+ * @returns {object|null}  filtered hooks, or null when nothing is inherited
+ */
+export function filterInheritedHooks(settingsHooks, allow) {
+  if (Array.isArray(allow) && allow.length === 0) return null; // none
+  if (!settingsHooks || typeof settingsHooks !== "object") return null;
+  if (!Array.isArray(allow)) return settingsHooks; // null = inherit all as-is
+
+  const allowSet = new Set(allow);
+  const matcherKey = (g) =>
+    g?.matcher == null || g.matcher === "" ? "*" : String(g.matcher);
+
+  const out = {};
+  for (const [event, groups] of Object.entries(settingsHooks)) {
+    if (!Array.isArray(groups)) continue;
+    const kept = groups.filter((g) => allowSet.has(matcherKey(g)));
+    if (kept.length > 0) out[event] = kept;
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}

package/src/lib/telemetry/span-recorder.js

@@ -12,6 +12,8 @@
  * `summary()` renders them. The clock is injected so tests are deterministic.
  */
 
+import { redactSecrets } from "../secret-scan.js";
+
 let _seq = 0;
 function spanId() {
   _seq = (_seq + 1) % Number.MAX_SAFE_INTEGER;
@@ -187,8 +189,19 @@ export class TelemetryRecorder {
     };
   }
 
-  /** OTLP/JSON-shaped export (resourceSpans) — ingestible by an OTel collector. */
-  toOtlp() {
+  /**
+   * OTLP/JSON-shaped export (resourceSpans) — ingestible by an OTel collector.
+   *
+   * §8.1 export gate: a span attribute or an exception message can carry a
+   * provider token / JWT / connection string (a tool `command` attribute, an
+   * error string, a redirect URL). A trace is shipped to a collector that may be
+   * external, so string values are secret-redacted by default (recall-first —
+   * an export must fail toward "no leak"). Only true secret substrings are
+   * replaced, so a span with no secret is byte-identical. `{ redact: false }`
+   * keeps raw values for a fully-trusted local collector.
+   */
+  toOtlp({ redact = true } = {}) {
+    const scrub = redact ? (v) => redactSecrets(String(v)) : (v) => String(v);
     return {
       resourceSpans: [
         {
@@ -219,14 +232,14 @@ export class TelemetryRecorder {
                       ? { doubleValue: v }
                       : typeof v === "boolean"
                         ? { boolValue: v }
-                        : { stringValue: String(v) },
+                        : { stringValue: scrub(v) },
                 })),
                 events: s.events.map((e) => ({
                   name: e.name,
                   timeUnixNano: String(Math.round(e.time * 1e6)),
                   attributes: Object.entries(e.attributes).map(([k, v]) => ({
                     key: k,
-                    value: { stringValue: String(v) },
+                    value: { stringValue: scrub(v) },
                   })),
                 })),
               })),

package/src/lib/terminal-context.js

@@ -0,0 +1,195 @@
+/**
+ * Terminal-context policy core — the pure-logic half of P1-2 (交互终端) of
+ * CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md.
+ *
+ * P1-2 asks for an embedded interactive PTY inside an Agent Session: continuous
+ * ANSI output, scrollback trimming, search/copy, user takeover, "把选中输出附加
+ * 到下一轮", background commands surfacing PID / port / health, and — critically —
+ * "Agent 不得把 Terminal 中的敏感输出默认加入模型上下文" (terminal output must NOT
+ * enter the model context by default).
+ *
+ * This module is that policy + text layer, NOT a PTY: it never spawns a shell,
+ * allocates a pseudo-terminal, or touches fs / clock / RNG / process. A caller
+ * (the real PTY host) feeds captured bytes and a selection intent and reads back
+ * what — if anything — is safe to hand the model.
+ *
+ * Two invariants give it teeth, mirroring the other gap cores:
+ *   1. Terminal output fails CLOSED out of the model context: `selectTerminal
+ *      ContextForModel` returns null unless the user EXPLICITLY opted this turn's
+ *      output in. Ambient scrollback never leaks into a prompt.
+ *   2. Whatever DOES get opted in is ANSI-stripped and secret-redacted (via
+ *      [[secret-scan.js]]) and scrollback-capped, so a printed token or a control
+ *      sequence can't ride into the context.
+ *
+ * PURE: no fs / clock / RNG / process / PTY.
+ */
+
+import { redactSecrets } from "./secret-scan.js";
+
+/**
+ * Match ANSI/VT control sequences: CSI (ESC [ … final byte), OSC (ESC ] … BEL or
+ * ST) and the standalone two/three-byte escapes. Kept explicit rather than a
+ * dependency so the strip is auditable (ESC = U+001B, CSI = U+009B, BEL = U+0007).
+ * A fresh RegExp is compiled per call to avoid the /g lastIndex
+ * hazard across invocations.
+ */
+function ansiRegex() {
+  return new RegExp(
+    [
+      "[\\u001B\\u009B][[\\]()#;?]*" +
+        "(?:(?:(?:[a-zA-Z\\d]*(?:;[a-zA-Z\\d]*)*)?\\u0007)" +
+        "|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PRZcf-ntqry=><~]))",
+    ].join(""),
+    "g",
+  );
+}
+
+/**
+ * Remove ANSI/VT escape sequences from terminal output, leaving human-readable
+ * text (for search, copy, and — importantly — before the text ever reaches a
+ * model, so escape codes can't smuggle intent or bloat the context). Non-string
+ * input → "".
+ */
+export function stripAnsi(text) {
+  if (typeof text !== "string") return "";
+  return text.replace(ansiRegex(), "");
+}
+
+/** Default scrollback cap — how many trailing lines survive truncation. */
+export const DEFAULT_SCROLLBACK_LINES = 400;
+
+/**
+ * Cap a captured buffer to its last `maxLines` lines (the live tail is what
+ * matters for a running process). Marks the elision so the reader — and any
+ * model — knows output was dropped rather than seeing a silently-truncated head.
+ *
+ * @returns {{text:string, truncated:boolean, droppedLines:number, totalLines:number}}
+ */
+export function truncateScrollback(text, maxLines = DEFAULT_SCROLLBACK_LINES) {
+  const src = typeof text === "string" ? text : "";
+  const cap =
+    Number.isInteger(maxLines) && maxLines > 0
+      ? maxLines
+      : DEFAULT_SCROLLBACK_LINES;
+  const lines = src.split("\n");
+  const total = lines.length;
+  if (total <= cap) {
+    return { text: src, truncated: false, droppedLines: 0, totalLines: total };
+  }
+  const kept = lines.slice(total - cap);
+  const dropped = total - cap;
+  return {
+    text: `…(${dropped} earlier lines elided)\n${kept.join("\n")}`,
+    truncated: true,
+    droppedLines: dropped,
+    totalLines: total,
+  };
+}
+
+/**
+ * Decide what terminal output may be attached to the next model turn — the
+ * fail-closed core of "Agent 不得把 Terminal 中的敏感输出默认加入模型上下文".
+ *
+ * Returns `null` (attach NOTHING) unless the user explicitly opted in this turn
+ * (`optIn === true`). When opted in, a supplied `selection` (the user's
+ * highlighted region) is preferred over the full `output` — "把选中输出附加到下
+ * 一轮". Whatever is chosen is ANSI-stripped, secret-redacted and scrollback-
+ * capped before it becomes context.
+ *
+ * @param {object} args
+ * @param {string} [args.output]     full captured terminal buffer
+ * @param {string} [args.selection]  user-highlighted region (preferred)
+ * @param {boolean} [args.optIn]     explicit "include this in context" intent
+ * @param {number} [args.maxLines]   scrollback cap for the attached text
+ * @returns {null | {source:"selection"|"output", text:string, truncated:boolean, redacted:boolean}}
+ */
+export function selectTerminalContextForModel(args = {}) {
+  const a = args && typeof args === "object" ? args : {};
+  if (a.optIn !== true) {
+    return null; // fail-closed: no ambient terminal output in the prompt
+  }
+  const hasSelection =
+    typeof a.selection === "string" && a.selection.trim() !== "";
+  const source = hasSelection ? "selection" : "output";
+  const raw = hasSelection ? a.selection : a.output;
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return null; // opted in but nothing to attach
+  }
+
+  const clean = stripAnsi(raw);
+  const redactedText = redactSecrets(clean);
+  const capped = truncateScrollback(redactedText, a.maxLines);
+  return {
+    source,
+    text: capped.text,
+    truncated: capped.truncated,
+    redacted: redactedText !== clean,
+  };
+}
+
+/** Canonical health states for a backgrounded terminal command. */
+export const HEALTH_STATUS = Object.freeze({
+  STARTING: "starting",
+  RUNNING: "running",
+  HEALTHY: "healthy",
+  UNHEALTHY: "unhealthy",
+  EXITED: "exited",
+  UNKNOWN: "unknown",
+});
+
+const HEALTH_ALIASES = new Map([
+  ["starting", HEALTH_STATUS.STARTING],
+  ["running", HEALTH_STATUS.RUNNING],
+  ["up", HEALTH_STATUS.RUNNING],
+  ["healthy", HEALTH_STATUS.HEALTHY],
+  ["ok", HEALTH_STATUS.HEALTHY],
+  ["unhealthy", HEALTH_STATUS.UNHEALTHY],
+  ["degraded", HEALTH_STATUS.UNHEALTHY],
+  ["exited", HEALTH_STATUS.EXITED],
+  ["stopped", HEALTH_STATUS.EXITED],
+  ["dead", HEALTH_STATUS.EXITED],
+]);
+
+/** Normalize a health label; anything unrecognized → UNKNOWN (fail-closed). */
+export function normalizeHealthStatus(value) {
+  if (typeof value !== "string") return HEALTH_STATUS.UNKNOWN;
+  return (
+    HEALTH_ALIASES.get(value.trim().toLowerCase()) || HEALTH_STATUS.UNKNOWN
+  );
+}
+
+function normalizePorts(ports) {
+  const list = Array.isArray(ports) ? ports : [];
+  const out = [];
+  for (const p of list) {
+    const n = Number(p);
+    if (Number.isInteger(n) && n > 0 && n <= 65535 && !out.includes(n)) {
+      out.push(n);
+    }
+  }
+  return out;
+}
+
+/**
+ * Build a safe descriptor for a backgrounded terminal command — the "后台命令显示
+ * PID、端口、健康状态并可安全停止" surface. The command string is secret-redacted
+ * (a `FOO=token cmd` invocation must not leak the token into a status pill), PID
+ * is coerced to a positive integer or null, ports are validated, and the health
+ * status is normalized fail-closed. `stoppable` is true only when we hold a real
+ * PID to signal.
+ *
+ * @param {object} cmd {command?, pid?, ports?, status?}
+ * @returns {{command:string|null, pid:number|null, ports:number[], status:string, stoppable:boolean}}
+ */
+export function describeBackgroundCommand(cmd = {}) {
+  const c = cmd && typeof cmd === "object" ? cmd : {};
+  const pidNum = Number(c.pid);
+  const pid = Number.isInteger(pidNum) && pidNum > 0 ? pidNum : null;
+  return {
+    command: typeof c.command === "string" ? redactSecrets(c.command) : null,
+    pid,
+    ports: normalizePorts(c.ports),
+    status: normalizeHealthStatus(c.status),
+    stoppable: pid !== null,
+  };
+}