clinkx 0.3.0 → 1.1.0

package/clinkx-workflows/dist/chairman-knobs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared chairman invocation-knob resolution.
+ *
+ * Provider change (caller chairman is set AND differs from the static
+ * cli_name) drops inherited model/effort; only explicit chairman knobs apply.
+ * Same provider keeps unspecified static pins and overlays supplied knobs.
+ */
+export interface ChairmanCallPins {
+    readonly cli_name: string;
+    readonly model?: string | undefined;
+    readonly effort?: string | undefined;
+}
+export interface ResolveEffectiveChairmanCallInput {
+    readonly staticCall: ChairmanCallPins;
+    readonly chairmanCliName: string | undefined;
+    readonly chairmanModel: string | undefined;
+    readonly chairmanEffort: string | undefined;
+}
+export interface EffectiveChairmanCall {
+    readonly cli_name: string;
+    readonly model?: string;
+    readonly effort?: string;
+}
+export declare function resolveEffectiveChairmanCall(input: ResolveEffectiveChairmanCallInput): EffectiveChairmanCall;

package/clinkx-workflows/dist/chairman-knobs.js

@@ -0,0 +1,27 @@
+/**
+ * Shared chairman invocation-knob resolution.
+ *
+ * Provider change (caller chairman is set AND differs from the static
+ * cli_name) drops inherited model/effort; only explicit chairman knobs apply.
+ * Same provider keeps unspecified static pins and overlays supplied knobs.
+ */
+export function resolveEffectiveChairmanCall(input) {
+    const { staticCall, chairmanCliName, chairmanModel, chairmanEffort } = input;
+    const providerChanged = chairmanCliName != null && chairmanCliName !== staticCall.cli_name;
+    const model = chairmanModel !== undefined
+        ? chairmanModel
+        : providerChanged
+            ? undefined
+            : staticCall.model;
+    const effort = chairmanEffort !== undefined
+        ? chairmanEffort
+        : providerChanged
+            ? undefined
+            : staticCall.effort;
+    return {
+        cli_name: chairmanCliName ?? staticCall.cli_name,
+        ...(model !== undefined ? { model } : {}),
+        ...(effort !== undefined ? { effort } : {}),
+    };
+}
+//# sourceMappingURL=chairman-knobs.js.map

package/clinkx-workflows/dist/chairman-knobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chairman-knobs.js","sourceRoot":"","sources":["../src/chairman-knobs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqBH,MAAM,UAAU,4BAA4B,CAC1C,KAAwC;IAExC,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;IAC7E,MAAM,eAAe,GACnB,eAAe,IAAI,IAAI,IAAI,eAAe,KAAK,UAAU,CAAC,QAAQ,CAAC;IACrE,MAAM,KAAK,GAAG,aAAa,KAAK,SAAS;QACvC,CAAC,CAAC,aAAa;QACf,CAAC,CAAC,eAAe;YACf,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC;IACvB,MAAM,MAAM,GAAG,cAAc,KAAK,SAAS;QACzC,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,eAAe;YACf,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;IAExB,OAAO;QACL,QAAQ,EAAE,eAAe,IAAI,UAAU,CAAC,QAAQ;QAChD,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/clinkx-workflows/dist/citation-check.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Citation check post-processor.
+ *
+ * Deterministically filters citation "evidence" in code-review schema outputs
+ * down to files that actually exist in the review's allowlist (the union of
+ * diff-touched files, caller-provided context_files, and curated
+ * context_bundle_files). Unverifiable evidence is dropped; findings are never
+ * deleted — when a finding's only support was unverifiable its confidence is
+ * capped so it cannot masquerade as high-confidence.
+ *
+ * Pure and side-effect free: operates on a deep clone of the input.
+ */
+/** Context handed to {@link citationCheck} by the post-processor registry. */
+export interface CitationCheckContext {
+    readonly allowlist: Set<string>;
+    readonly schemaId: string;
+}
+/**
+ * Add a path and its basename to the allowlist so matching is lenient
+ * (a citation may reference either the repo-relative path or the bare file).
+ */
+export declare function addPathWithBasename(set: Set<string>, p: string): void;
+/**
+ * Parse a unified diff string into an allowlist of touched files (full path
+ * plus basename for each). Recognizes `diff --git a/x b/x`, `+++ b/x`, and
+ * `--- a/x` header lines. `/dev/null` sentinels are excluded.
+ */
+export declare function buildAllowlistFromDiff(diff: string): Set<string>;
+/**
+ * Filter unverifiable citations from a code-review schema artifact.
+ *
+ * Only acts when `ctx.schemaId` identifies a code-review schema (id includes
+ * `"code_review"`); otherwise the input is returned unchanged. Both the
+ * reviewer and cross-reviewer shapes are handled defensively — missing/optional
+ * fields are tolerated, and the input is deep-cloned before mutation.
+ */
+export declare function citationCheck(validated: unknown, ctx: {
+    allowlist: Set<string>;
+    schemaId: string;
+}): unknown;

package/clinkx-workflows/dist/citation-check.js

@@ -0,0 +1,348 @@
+/**
+ * Citation check post-processor.
+ *
+ * Deterministically filters citation "evidence" in code-review schema outputs
+ * down to files that actually exist in the review's allowlist (the union of
+ * diff-touched files, caller-provided context_files, and curated
+ * context_bundle_files). Unverifiable evidence is dropped; findings are never
+ * deleted — when a finding's only support was unverifiable its confidence is
+ * capped so it cannot masquerade as high-confidence.
+ *
+ * Pure and side-effect free: operates on a deep clone of the input.
+ */
+import { basename } from "node:path";
+/** Confidence ceiling applied to findings/refs whose citations don't verify. */
+const UNVERIFIED_CONFIDENCE_CAP = 50;
+// ---------------------------------------------------------------------------
+// Allowlist construction
+// ---------------------------------------------------------------------------
+/**
+ * Add a path and its basename to the allowlist so matching is lenient
+ * (a citation may reference either the repo-relative path or the bare file).
+ */
+export function addPathWithBasename(set, p) {
+    if (typeof p !== "string" || p.length === 0) {
+        return;
+    }
+    set.add(p);
+    set.add(basename(p));
+}
+/** Strip a unified-diff `a/` or `b/` path prefix. */
+function stripDiffPrefix(token) {
+    if (token.startsWith("a/") || token.startsWith("b/")) {
+        return token.slice(2);
+    }
+    return token;
+}
+/**
+ * Parse a unified diff string into an allowlist of touched files (full path
+ * plus basename for each). Recognizes `diff --git a/x b/x`, `+++ b/x`, and
+ * `--- a/x` header lines. `/dev/null` sentinels are excluded.
+ */
+export function buildAllowlistFromDiff(diff) {
+    const set = new Set();
+    if (typeof diff !== "string" || diff.length === 0) {
+        return set;
+    }
+    for (const line of diff.split(/\r?\n/)) {
+        if (line.startsWith("diff --git ")) {
+            const rest = line.slice("diff --git ".length).trim();
+            for (const token of rest.split(/\s+/)) {
+                addPathWithBasename(set, stripDiffPrefix(token));
+            }
+        }
+        else if (line.startsWith("+++ ") || line.startsWith("--- ")) {
+            addPathWithBasename(set, stripDiffPrefix(line.slice(4).trim()));
+        }
+    }
+    set.delete("/dev/null");
+    set.delete("null");
+    return set;
+}
+// ---------------------------------------------------------------------------
+// Matching helpers
+// ---------------------------------------------------------------------------
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Extract the file portion of a `path` or `path:line` location string. */
+function fileFromLocation(location) {
+    if (typeof location !== "string" || location.length === 0) {
+        return undefined;
+    }
+    const colon = location.indexOf(":");
+    const file = colon === -1 ? location : location.slice(0, colon);
+    return file.length > 0 ? file : undefined;
+}
+/**
+ * True when `shorter` is a separator-aware path-suffix of `longer` (or equal):
+ * `src/foo.ts` is a suffix of `/abs/src/foo.ts` (the latter ends with `/` +
+ * the former). Handles both `/` and `\` separators. Used to recognize that the
+ * relative and absolute forms of the SAME file are not two distinct files.
+ */
+function isPathSuffix(longer, shorter) {
+    if (longer === shorter) {
+        return true;
+    }
+    if (longer.length <= shorter.length || !longer.endsWith(shorter)) {
+        return false;
+    }
+    const boundary = longer[longer.length - shorter.length - 1];
+    return boundary === "/" || boundary === "\\";
+}
+/**
+ * Count, per basename, how many DISTINCT FILE IDENTITIES in the allowlist share
+ * that basename.
+ *
+ * The allowlist is a flat Set mixing full repo-relative paths AND bare
+ * basenames (see {@link addPathWithBasename}). To decide whether a basename
+ * match is *unambiguous* we only consider path-bearing entries — i.e. entries
+ * that contain a path separator. (A bare-basename entry carries no directory
+ * information, so it cannot disambiguate one directory from another.)
+ *
+ * Crucially, the engine's `resolvePathListLenient` adds BOTH the raw-relative
+ * and the resolved-absolute form of each context file, so one real file yields
+ * two string-distinct entries (`src/foo.ts` and `/abs/.../src/foo.ts`) that
+ * share a basename. Counting those as 2 would wrongly mark a legitimate
+ * bare-basename citation as ambiguous. So within each basename group we collapse
+ * entries where one path is a separator-aware suffix of another (the same file
+ * in two forms) and count only the resulting distinct identities. Two genuinely
+ * different files (`src/a/foo.ts`, `src/b/foo.ts`) are not suffixes of each
+ * other, so they remain count 2 — correctly ambiguous.
+ *
+ * When a basename maps to two-or-more distinct identities it is ambiguous, so a
+ * basename-only citation is rejected; mapping to 0 or 1 is unambiguous and
+ * accepted (see {@link isAllowedFile}).
+ *
+ * Note: this is advisory defense-in-depth against fabricated LLM citations,
+ * not a security boundary.
+ */
+function buildBasenameMultiplicity(allowlist) {
+    // Bucket path-bearing entries by basename first, deduping exact strings.
+    const groups = new Map();
+    const seenPaths = new Set();
+    for (const entry of allowlist) {
+        // Only path-bearing entries (those with a separator) disambiguate.
+        if (!entry.includes("/") && !entry.includes("\\")) {
+            continue;
+        }
+        if (seenPaths.has(entry)) {
+            continue;
+        }
+        seenPaths.add(entry);
+        const base = basename(entry);
+        const group = groups.get(base);
+        if (group === undefined) {
+            groups.set(base, [entry]);
+        }
+        else {
+            group.push(entry);
+        }
+    }
+    // Within each (tiny) group, collapse suffix-duplicates of the same file to a
+    // single identity. O(group^2); groups are small.
+    const counts = new Map();
+    for (const [base, paths] of groups) {
+        let identities = 0;
+        for (let i = 0; i < paths.length; i++) {
+            const candidate = paths[i];
+            let collapsed = false;
+            for (let j = 0; j < paths.length; j++) {
+                if (i === j) {
+                    continue;
+                }
+                const other = paths[j];
+                // `candidate` collapses into `other` when `candidate` is a suffix of the
+                // strictly longer `other` (so each same-file pair is counted exactly
+                // once, via its longest/absolute form).
+                if (other.length > candidate.length && isPathSuffix(other, candidate)) {
+                    collapsed = true;
+                    break;
+                }
+            }
+            if (!collapsed) {
+                identities++;
+            }
+        }
+        counts.set(base, identities);
+    }
+    return counts;
+}
+/**
+ * A file citation is verified when:
+ *  - it carries a directory component and exactly matches a full-path allowlist
+ *    entry; OR
+ *  - it is a bare basename present in the allowlist whose basename is
+ *    unambiguous (fewer than two distinct full paths share it).
+ *
+ * The basename fallback is deliberately conservative: common filenames
+ * (index.ts, schema.ts, handler.ts) collide across directories, so a
+ * directory-qualified citation that does not match a full path is NOT downgraded
+ * to a basename match — this stops a fabricated `src/unrelated/schema.ts` from
+ * riding on an unrelated `schema.ts` already in the allowlist. Advisory
+ * defense-in-depth, not a security boundary.
+ */
+function isAllowedFile(file, allowlist, basenameMultiplicity) {
+    const base = basename(file);
+    // Citation carries a directory component: require an exact full-path match.
+    // Do NOT fall back to a basename match — a citation that was specific about a
+    // directory that isn't allowed (e.g. a fabricated `src/unrelated/schema.ts`)
+    // must not ride on an allowed `src/other/schema.ts`. Note we cannot rely on
+    // `allowlist.has(file)` alone for the bare case because the allowlist also
+    // stores bare basenames (see addPathWithBasename), so a bare-basename
+    // citation would always "match" without the multiplicity gate below.
+    if (file !== base) {
+        return allowlist.has(file);
+    }
+    // Bare-basename citation: accept only when that basename is present AND
+    // unambiguous. Ambiguity means TWO OR MORE distinct full paths share the
+    // basename — only then could the bare citation point at the wrong file.
+    // Multiplicity 0 (the entry exists only as a bare basename / a root-level
+    // file with no directory variants) or 1 is unambiguous and accepted; >=2 is
+    // rejected.
+    if (!allowlist.has(base)) {
+        return false;
+    }
+    return (basenameMultiplicity.get(base) ?? 0) < 2;
+}
+/**
+ * Cap a finding/ref's confidence to {@link UNVERIFIED_CONFIDENCE_CAP} because
+ * its citation did not verify. Confidence is OPTIONAL in the schema, so:
+ *  - if it is already a number, lower it to the cap (never raised);
+ *  - if it is absent / non-numeric, SET it to the cap so every unverifiable
+ *    finding carries an explicit low-confidence signal.
+ * Mutates the (deep-cloned) record in place; never deletes the finding/ref.
+ */
+function capUnverifiedConfidence(record) {
+    const existing = record["confidence"];
+    const numeric = typeof existing === "number" ? existing : undefined;
+    record["confidence"] = Math.min(numeric ?? UNVERIFIED_CONFIDENCE_CAP, UNVERIFIED_CONFIDENCE_CAP);
+}
+/** An evidence entry is verifiable iff its `.location` file is in the allowlist. */
+function isAllowedEvidence(entry, allowlist, basenameMultiplicity) {
+    const file = fileFromLocation(isRecord(entry) ? entry["location"] : undefined);
+    if (file === undefined) {
+        return false;
+    }
+    return isAllowedFile(file, allowlist, basenameMultiplicity);
+}
+// ---------------------------------------------------------------------------
+// Schema walks
+// ---------------------------------------------------------------------------
+/**
+ * Reviewer schema: validate `<key>[].file` and filter `<key>[].evidence[]`
+ * against the allowlist. Confidence is capped/set to {@link UNVERIFIED_CONFIDENCE_CAP}
+ * when EITHER the finding's top-level `file` is set but not allowed (a fabricated
+ * primary file — mirrors {@link processRefs} semantics), OR the finding had
+ * evidence that was entirely filtered out. Because confidence is OPTIONAL, an
+ * unverified finding that OMITS confidence gets it SET to the cap so it can't
+ * masquerade as unscored/high-confidence (see {@link capUnverifiedConfidence}).
+ * Never remove the finding itself.
+ */
+function processReviewerFindings(root, key, allowlist, basenameMultiplicity) {
+    const findings = root[key];
+    if (!Array.isArray(findings)) {
+        return;
+    }
+    for (const finding of findings) {
+        if (!isRecord(finding)) {
+            continue;
+        }
+        // Top-level `file` validation (mirrors processRefs). A fabricated primary
+        // file caps confidence even when the finding carries no evidence, or carries
+        // valid evidence pointing at a *different* allowed file.
+        const file = finding["file"];
+        const fileUnverified = typeof file === "string" &&
+            file.length > 0 &&
+            !isAllowedFile(file, allowlist, basenameMultiplicity);
+        let evidenceUnverified = false;
+        const evidence = finding["evidence"];
+        if (Array.isArray(evidence)) {
+            const hadEvidence = evidence.length > 0;
+            const kept = evidence.filter((entry) => isAllowedEvidence(entry, allowlist, basenameMultiplicity));
+            finding["evidence"] = kept;
+            evidenceUnverified = hadEvidence && kept.length === 0;
+        }
+        if (fileUnverified || evidenceUnverified) {
+            capUnverifiedConfidence(finding);
+        }
+    }
+}
+/**
+ * Cross-reviewer refs: drop invalid evidence; cap/set confidence to the cap when
+ * EITHER the ref's `.file` is set but not in the allowlist (a fabricated primary
+ * file), OR the ref HAD evidence that was entirely filtered out (mirrors
+ * {@link processReviewerFindings} semantics — `file`, `evidence`, and
+ * `confidence` are all OPTIONAL in the cross-review ref schema, so a ref with no
+ * `file`, fabricated evidence, and no `confidence` must still be downgraded). An
+ * omitted confidence value is SET to the cap so it cannot masquerade as
+ * unscored/high-confidence. Refs are never dropped.
+ */
+function processRefs(refs, allowlist, basenameMultiplicity) {
+    if (!Array.isArray(refs)) {
+        return;
+    }
+    for (const ref of refs) {
+        if (!isRecord(ref)) {
+            continue;
+        }
+        let evidenceUnverified = false;
+        const evidence = ref["evidence"];
+        if (Array.isArray(evidence)) {
+            const hadEvidence = evidence.length > 0;
+            const kept = evidence.filter((entry) => isAllowedEvidence(entry, allowlist, basenameMultiplicity));
+            ref["evidence"] = kept;
+            evidenceUnverified = hadEvidence && kept.length === 0;
+        }
+        const file = ref["file"];
+        const fileUnverified = typeof file === "string" &&
+            file.length > 0 &&
+            !isAllowedFile(file, allowlist, basenameMultiplicity);
+        if (fileUnverified || evidenceUnverified) {
+            capUnverifiedConfidence(ref);
+        }
+    }
+}
+function processCrossReviewer(root, allowlist, basenameMultiplicity) {
+    const feedback = root["per_review_feedback"];
+    if (!Array.isArray(feedback)) {
+        return;
+    }
+    for (const fb of feedback) {
+        if (!isRecord(fb)) {
+            continue;
+        }
+        processRefs(fb["missed_issue_refs"], allowlist, basenameMultiplicity);
+        processRefs(fb["false_positive_refs"], allowlist, basenameMultiplicity);
+    }
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/**
+ * Filter unverifiable citations from a code-review schema artifact.
+ *
+ * Only acts when `ctx.schemaId` identifies a code-review schema (id includes
+ * `"code_review"`); otherwise the input is returned unchanged. Both the
+ * reviewer and cross-reviewer shapes are handled defensively — missing/optional
+ * fields are tolerated, and the input is deep-cloned before mutation.
+ */
+export function citationCheck(validated, ctx) {
+    if (!ctx.schemaId.includes("code_review")) {
+        return validated;
+    }
+    const clone = structuredClone(validated);
+    if (!isRecord(clone)) {
+        return clone;
+    }
+    // Precompute basename → full-path multiplicity once per call so the matching
+    // helpers can reject ambiguous basename-only citations (Fix #4).
+    const basenameMultiplicity = buildBasenameMultiplicity(ctx.allowlist);
+    // Reviewer schema locations.
+    processReviewerFindings(clone, "blocking_issues", ctx.allowlist, basenameMultiplicity);
+    processReviewerFindings(clone, "structural_findings", ctx.allowlist, basenameMultiplicity);
+    // Cross-reviewer schema locations.
+    processCrossReviewer(clone, ctx.allowlist, basenameMultiplicity);
+    return clone;
+}
+//# sourceMappingURL=citation-check.js.map

package/clinkx-workflows/dist/citation-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-check.js","sourceRoot":"","sources":["../src/citation-check.ts"],"names":[],"mappings":"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"}

package/clinkx-workflows/dist/clink-client.d.ts

@@ -13,6 +13,8 @@
  * - Only output_text is stored/threaded/hashed
  */
 import type { ClinkBackend, ToolCallResult } from "./backend.js";
+import type { SessionLogOwnerV1 } from "./dashboard/session-log-contract.js";
+import { type ObservedInvocationV1 } from "./dashboard/invocation-contract.js";
 /** Parsed result from a clink call. */
 export interface ClinkCallResult {
     /** Primary output text (for storage/threading/hashing). */
@@ -48,4 +50,13 @@ export declare function parseCallResult(result: ToolCallResult): ClinkCallResult
 export declare function callClink(session: ClinkBackend, input: Record<string, unknown>, signal?: AbortSignal, context?: {
     stageId: string;
     callId: string;
-}, timeoutMs?: number): Promise<ClinkCallResult>;
+}, timeoutMs?: number, sessionLogOwner?: SessionLogOwnerV1): Promise<ClinkCallResult>;
+/**
+ * Extract a runtime-observed invocation record from a child `_debug` block.
+ *
+ * Best-effort telemetry: returns undefined when the block is absent, the
+ * `observed_invocation` key is missing, or the payload does not satisfy
+ * ObservedInvocationV1Schema. Never throws — malformed observed telemetry
+ * must not affect call success/failure handling.
+ */
+export declare function extractObservedInvocation(debug: Record<string, unknown> | null): ObservedInvocationV1 | undefined;

package/clinkx-workflows/dist/clink-client.js

@@ -15,6 +15,8 @@
 import { InvalidCallError, CallExecutionError } from "./errors.js";
 import { logger } from "./logger.js";
 import { basename } from "node:path";
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { ObservedInvocationV1Schema, } from "./dashboard/invocation-contract.js";
 /**
  * Build the tool arguments for a child clink call.
  *
@@ -24,12 +26,16 @@ import { basename } from "node:path";
 export function buildCallArgs(input) {
     // Clone to avoid mutating caller's input
     const args = { ...input };
+    delete args["sessionLogOwner"];
+    delete args["session_log_owner"];
     // Always enable debug for internal calls
     args["debug"] = true;
     // Strip host _meta.progressToken (1-11a: progress isolation)
     if (args["_meta"] != null && typeof args["_meta"] === "object") {
         const meta = { ...args["_meta"] };
         delete meta["progressToken"];
+        delete meta["sessionLogOwner"];
+        delete meta["session_log_owner"];
         // Only keep _meta if it still has keys
         if (Object.keys(meta).length > 0) {
             args["_meta"] = meta;
@@ -96,16 +102,17 @@ function sanitizeDebugMetadataForLog(debug) {
  * @throws InvalidCallError on child -32602
  * @throws CallExecutionError on child isError: true
  */
-export async function callClink(session, input, signal, context, timeoutMs) {
+export async function callClink(session, input, signal, context, timeoutMs, sessionLogOwner) {
     const args = buildCallArgs(input);
     const stageId = context?.stageId ?? "unknown";
     const callId = context?.callId ?? "unknown";
     let result;
     try {
-        result = await session.callTool(args, signal != null || timeoutMs != null
+        result = await session.callTool(args, signal != null || timeoutMs != null || sessionLogOwner != null
             ? {
                 ...(signal != null ? { signal } : {}),
                 ...(timeoutMs != null ? { timeoutMs } : {}),
+                ...(sessionLogOwner != null ? { sessionLogOwner } : {}),
             }
             : undefined);
     }
@@ -114,6 +121,12 @@ export async function callClink(session, input, signal, context, timeoutMs) {
         if (isMcpInvalidParams(err)) {
             throw new InvalidCallError(`Child rejected call as invalid: ${err instanceof Error ? err.message : String(err)}`, stageId, callId);
         }
+        // The MCP SDK emits this structured code when its RequestOptions.timeout
+        // expires. Preserve it as an internal wall-timeout discriminant so the
+        // engine can apply council policy without relying on error text.
+        if (isMcpRequestTimeout(err)) {
+            throw new CallExecutionError(`Child clink request timed out: ${err instanceof Error ? err.message : String(err)}`, stageId, callId, thrownFailureClass(err), undefined, "wall");
+        }
         throw err;
     }
     // Map child isError: true to CallExecutionError
@@ -121,11 +134,20 @@ export async function callClink(session, input, signal, context, timeoutMs) {
         const parsed = parseCallResult(result);
         const failureClass = classifyFailure(parsed.debugMetadata);
         const childDebugMetadata = extractChildFailureMetadata(parsed.debugMetadata);
+        const terminationReasonValue = parsed.debugMetadata?.["termination_reason"];
+        const terminationReason = terminationReasonValue === "wall" || terminationReasonValue === "idle"
+            ? terminationReasonValue
+            : undefined;
         // Fallback: if pipeline missed the panic class (e.g. wrapper formatting
         // differences), detect the codex-local crash signature in output text.
+        // Structured metadata takes precedence: when the child's _debug already
+        // carries a codex_panic_class, trust that classification and skip
+        // prose re-synthesis (kept only for old children without structured _debug).
         let effectiveFailureClass = failureClass;
         let effectiveChildDebugMetadata = childDebugMetadata;
-        if (failureClass === "permanent" && parsed.outputText != null) {
+        if (failureClass === "permanent" &&
+            parsed.outputText != null &&
+            childDebugMetadata?.codex_panic_class == null) {
             const codexLocalMatch = parsed.outputText.match(/\[codex-local\]:?\s*Local Codex process failed(?::\s*Process exited with code:\s*(\d+))?/);
             if (codexLocalMatch != null) {
                 const exitCode = codexLocalMatch[1] != null ? Number(codexLocalMatch[1]) : null;
@@ -150,10 +172,24 @@ export async function callClink(session, input, signal, context, timeoutMs) {
             effective_failure_class: effectiveFailureClass,
             debug: sanitizeDebugMetadataForLog(parsed.debugMetadata),
         }, "child clink call returned isError");
-        throw new CallExecutionError(parsed.outputText || "Child clink call failed", stageId, callId, effectiveFailureClass, effectiveChildDebugMetadata);
+        throw new CallExecutionError(parsed.outputText || "Child clink call failed", stageId, callId, effectiveFailureClass, effectiveChildDebugMetadata, terminationReason);
     }
     return parseCallResult(result);
 }
+/**
+ * Extract a runtime-observed invocation record from a child `_debug` block.
+ *
+ * Best-effort telemetry: returns undefined when the block is absent, the
+ * `observed_invocation` key is missing, or the payload does not satisfy
+ * ObservedInvocationV1Schema. Never throws — malformed observed telemetry
+ * must not affect call success/failure handling.
+ */
+export function extractObservedInvocation(debug) {
+    if (debug == null)
+        return undefined;
+    const parsed = ObservedInvocationV1Schema.safeParse(debug["observed_invocation"]);
+    return parsed.success ? parsed.data : undefined;
+}
 /**
  * Panic classes confirmed as transient (retryable). Only classes with strong
  * evidence of being transport-layer failures belong here. `codex_local_crash`
@@ -222,11 +258,14 @@ function extractChildFailureMetadata(debug) {
         adapter_config_path: typeof debug["adapter_config_path"] === "string" ? debug["adapter_config_path"] : undefined,
         exit_code: typeof debug["exit_code"] === "number" || debug["exit_code"] === null ? debug["exit_code"] : undefined,
         codex_panic_class: typeof debug["codex_panic_class"] === "string" ? debug["codex_panic_class"] : undefined,
+        semantic_failure_reason: typeof debug["semantic_failure_reason"] === "string" ? debug["semantic_failure_reason"] : undefined,
+        secondary_failure_reason: typeof debug["secondary_failure_reason"] === "string" ? debug["secondary_failure_reason"] : undefined,
     };
     // Only return if at least one field is present
     const hasContent = meta.rejection_reason != null || meta.parse_status != null ||
         meta.parse_source != null || meta.adapter_config_path != null || meta.exit_code !== undefined ||
-        meta.codex_panic_class != null;
+        meta.codex_panic_class != null || meta.semantic_failure_reason != null ||
+        meta.secondary_failure_reason != null;
     return hasContent ? meta : undefined;
 }
 /**
@@ -238,4 +277,16 @@ function isMcpInvalidParams(err) {
     const code = err["code"];
     return code === -32602;
 }
+function isMcpRequestTimeout(err) {
+    if (err == null || typeof err !== "object")
+        return false;
+    const code = err["code"];
+    return code === ErrorCode.RequestTimeout;
+}
+function thrownFailureClass(err) {
+    if (err == null || typeof err !== "object")
+        return "permanent";
+    const failureClass = err["failureClass"];
+    return failureClass === "transient" ? "transient" : "permanent";
+}
 //# sourceMappingURL=clink-client.js.map