brainclaw 1.17.0 → 1.19.0

package/dist/core/dispatcher.js

@@ -34,9 +34,10 @@
  * @module
  */
 import { buildClaimEnvPrefix } from './execution-profile.js';
-import { getActiveSequence } from './sequence.js';
+import { getActiveSequence, listSequences } from './sequence.js';
 import { loadState, persistState } from './state.js';
 import { listClaims, createCoordinatorClaim, attachAssignmentMessageToClaim, linkClaimToAssignment, assessClaimLiveness } from './claims.js';
+import { sanitizeBranchComponent, isBranchMergedByContent, probeLocalBranch, isGitRepo } from './worktree.js';
 import { listAgentIdentities, ensureAgentRegisteredForDispatch } from './agent-registry.js';
 import { sendMessage, hasActiveAssignment } from './messaging.js';
 import { memoryDir } from './io.js';
@@ -64,14 +65,23 @@ function buildEnvPrefix(claimId) {
 }
 // ── Lane Analysis ───────────────────────────────────────────
 /**
- * Analyze the active sequence and categorize each item as ready, active, blocked, or done.
+ * Analyze a sequence and categorize each item as ready, active, blocked, or done.
+ *
+ * `sequenceId` (pln#632 impl-loop bind) targets a SPECIFIC sequence by id instead of
+ * the project's active one — so an implementation loop can dispatch its own linked
+ * sequence without hijacking the global active-sequence pointer. Omitted → the active
+ * sequence (byte-identical to the historical behaviour; the resolver is non-throwing,
+ * so an unknown id yields `null` exactly like "no active sequence").
  */
-export function analyzeSequence(cwd) {
-    const sequence = getActiveSequence(cwd);
+export function analyzeSequence(cwd, sequenceId) {
+    const sequence = sequenceId
+        ? listSequences(cwd).find((s) => s.id === sequenceId)
+        : getActiveSequence(cwd);
     if (!sequence)
         return null;
     const state = loadState(cwd);
-    const claims = listClaims(cwd).filter(c => c.status === 'active');
+    const allClaimsSnapshot = listClaims(cwd);
+    const claims = allClaimsSnapshot.filter(c => c.status === 'active');
     const agents = listAgentIdentities(cwd);
     // Index plans by ID for fast lookup
     const planIndex = new Map();
@@ -80,12 +90,36 @@ export function analyzeSequence(cwd) {
         if (p.short_label)
             planIndex.set(p.short_label, p);
     }
-    // Collect plan IDs that are done or dropped (terminal states)
+    // pln#529 — index sequence items by planId (scope_hint fallback for branch
+    // derivation).
+    const itemByPlanId = new Map();
+    for (const it of sequence.items)
+        itemByPlanId.set(it.planId, it);
+    // pln#529 (review Finding 1) — GROUND-TRUTH predecessor branch resolution: a
+    // predecessor lane's branch was created by createCoordinatorClaim from its
+    // CLAIM scope (which is stable across the coordinate/assign paths + survives a
+    // later scope_hint edit + persists on release). Re-deriving from live sequence
+    // metadata probes the wrong branch and silently defaults to HEAD. So resolve
+    // the predecessor's scope from its persisted claim (any claim for the plan;
+    // retries reuse the scope), falling back to the sequence item only when no
+    // claim exists.
+    const claimByPlanId = new Map();
+    for (const c of allClaimsSnapshot) {
+        if (c.plan_id)
+            claimByPlanId.set(c.plan_id, c);
+    }
+    const canonicalPlanId = (id) => planIndex.get(id)?.id ?? id;
+    const scopeForPred = (predId) => claimByPlanId.get(canonicalPlanId(predId))?.scope ?? itemByPlanId.get(predId)?.scope_hint ?? predId;
+    // Collect plan IDs that are done or dropped (terminal → gate-open) and the
+    // dropped subset (excluded from socle-fork: never propagate abandoned code —
+    // review Finding 6).
     const terminalPlanIds = new Set();
+    const droppedPlanIds = new Set();
     for (const p of state.plan_items) {
-        if (p.status === 'done' || p.status === 'dropped') {
+        if (p.status === 'done' || p.status === 'dropped')
             terminalPlanIds.add(p.id);
-        }
+        if (p.status === 'dropped')
+            droppedPlanIds.add(p.id);
     }
     // Collect plan IDs with active claims
     const claimedPlanIds = new Map();
@@ -150,16 +184,40 @@ export function analyzeSequence(cwd) {
             });
             continue;
         }
+        // pln#529 (dec#122 B+A) — for a gated lane, readiness ≠ code-availability:
+        // resolve the fork base by CONTENT. A ≥2-unintegrated diamond keeps the gate
+        // CLOSED (A); otherwise the lane is ready with its resolved base (HEAD, or a
+        // predecessor branch when the socle isn't on HEAD yet — B).
+        if (item.hard_after.length > 0) {
+            // Socle-fork considers DONE predecessors only — a dropped predecessor still
+            // satisfies the gate but its abandoned code must not be propagated (#6).
+            const socleDeps = item.hard_after.filter((id) => !droppedPlanIds.has(canonicalPlanId(id)));
+            const base = resolveGatedLaneBase(socleDeps, scopeForPred, cwd);
+            if (base.gateBlocked) {
+                blocked.push({
+                    item,
+                    plan,
+                    lane: item.lane,
+                    reason: base.gateBlocked.reason,
+                    blocked_by: base.gateBlocked.unintegrated,
+                });
+                continue;
+            }
+            ready.push({
+                item,
+                plan,
+                lane: item.lane,
+                reason: `All hard dependencies met${softNote}`,
+                worktreeBase: base,
+                code_propagation_note: base.reason,
+            });
+            continue;
+        }
         ready.push({
             item,
             plan,
             lane: item.lane,
             reason: `All hard dependencies met${softNote}`,
-            // pln#529 — readiness ≠ code-availability for gated lanes.
-            ...(item.hard_after.length > 0 ? {
-                code_propagation_note: `Unblocked by hard_after [${item.hard_after.join(', ')}]. Ensure that work is committed AND on the dispatch base (HEAD), ` +
-                    `or dispatch this lane with ref=<predecessor branch> — otherwise the worker spawns from HEAD without it.`,
-            } : {}),
         });
     }
     // Build capacity summary per agent (multi-instance aware)
@@ -631,20 +689,113 @@ function countCycleByResource(cycleAssignments, resourceKey) {
     }
     return total;
 }
-export function selectWorktreeBaseForReadyLane(item, analysis) {
-    const hardAfter = item.hard_after ?? [];
+/**
+ * pln#529 (dec#122 B+A) — resolve the fork base for a gated lane whose hard_after
+ * predecessors are all DONE (dropped predecessors are excluded by the caller —
+ * their abandoned code must not be propagated). "Readiness ≠ code-availability":
+ * a done predecessor's code may be committed on its own branch but NOT integrated
+ * on HEAD (the standard squash-merge breaks ancestry — trp#926 — so integration
+ * is detected by CONTENT via `isBranchMergedByContent`, patch-id + file-content,
+ * not ancestry).
+ *
+ * `scopeFor(predId)` MUST return the GROUND-TRUTH scope the predecessor's branch
+ * was created from — its persisted claim scope (review Finding 1). Re-deriving
+ * the branch from live/mutable sequence metadata probes the wrong branch under
+ * the coordinate(assign) path or an edited scope_hint, and the miss silently
+ * defaults to HEAD — the very socle-drop this feature closes.
+ *
+ * `cwd` MUST be the project's MAIN git worktree (HEAD = the integration target);
+ * `analyzeSequence` is the sole production caller and passes the coordinator root.
+ *
+ * Per predecessor (branch = `feat/<sanitized scope>`), by tri-state probe:
+ *   - present + content-merged → verified on HEAD;
+ *   - present + NOT merged     → committed-but-unintegrated (fork candidate);
+ *   - absent (clean not-found) → ASSUMED on HEAD (merged + branch cleaned up) —
+ *     honestly labelled "assumed", never claimed "verified";
+ *   - unknown (git probe FAILED) → unverifiable → fail SAFE (gateBlocked), never
+ *     silently "on HEAD" (review Finding 3).
+ * Then: any unverifiable, or ≥2 fork-candidates → gateBlocked (A); exactly 1
+ * fork-candidate → fork from it (B); else baseRef HEAD (A satisfied).
+ */
+export function resolveGatedLaneBase(hardAfter, scopeFor, cwd) {
     if (hardAfter.length === 0)
         return {};
-    const donePlanIds = new Set(analysis.done.map((entry) => entry.planId));
-    const allHardDepsDone = hardAfter.every((planId) => donePlanIds.has(planId));
-    if (!allHardDepsDone)
-        return {};
+    // Non-git project → branch/worktree socle propagation is inapplicable; keep the
+    // legacy HEAD base (the tri-state "unknown" fail-safe is ONLY for a git repo
+    // whose branch probe transiently failed, not for a project that has no git at
+    // all — otherwise every non-git gated lane would wrongly gate-block).
+    if (!isGitRepo(cwd)) {
+        return { baseRef: 'HEAD', resetExistingBranch: true, reason: 'non-git project — socle propagation not applicable; base = HEAD' };
+    }
+    const unintegrated = [];
+    const unverifiable = [];
+    const verifiedOnHead = [];
+    const assumedOnHead = [];
+    for (const predId of hardAfter) {
+        const branch = `feat/${sanitizeBranchComponent(scopeFor(predId))}`;
+        const probe = probeLocalBranch(cwd, branch);
+        if (probe === 'unknown') {
+            unverifiable.push({ planId: predId, branch });
+            continue;
+        }
+        if (probe === 'absent') {
+            assumedOnHead.push(predId);
+            continue;
+        } // merged + branch GC'd
+        if (isBranchMergedByContent(cwd, branch, 'HEAD')) {
+            verifiedOnHead.push(predId);
+            continue;
+        }
+        unintegrated.push({ planId: predId, branch });
+    }
+    // Fail SAFE: a git probe we could not complete must NOT open the gate on a
+    // "HEAD is fine" assumption. Combine with the ≥2-fork-candidate diamond.
+    if (unverifiable.length > 0 || unintegrated.length >= 2) {
+        const parts = [
+            ...unintegrated.map((u) => `${u.planId}→${u.branch} (committed, not on HEAD)`),
+            ...unverifiable.map((u) => `${u.planId}→${u.branch} (integration UNVERIFIABLE — git probe failed)`),
+        ];
+        return {
+            gateBlocked: {
+                reason: `pln#529(A): cannot safely resolve a single fork base for this gated lane — ${parts.join('; ')}. Integrate the un-integrated predecessors onto HEAD (merge/squash), or retry once git is reachable; a single worktree cannot fork from multiple bases without silently dropping a predecessor's code.`,
+                unintegrated: [...unintegrated, ...unverifiable].map((u) => u.planId),
+            },
+        };
+    }
+    const headNote = (verb) => `${verb}${verifiedOnHead.length ? ` content-verified on HEAD: ${verifiedOnHead.join(', ')}` : ''}` +
+        `${assumedOnHead.length ? `${verifiedOnHead.length ? '; ' : ' '}assumed on HEAD (branch absent — merged + cleaned, unverifiable): ${assumedOnHead.join(', ')}` : ''}`;
+    if (unintegrated.length === 1) {
+        const u = unintegrated[0];
+        return {
+            baseRef: u.branch,
+            resetExistingBranch: true,
+            reason: `pln#529(B): predecessor ${u.planId} is committed on ${u.branch} but not yet integrated on HEAD — the dependent lane forks from that branch so it carries the socle code. (${headNote('Other predecessors:')})`,
+        };
+    }
     return {
         baseRef: 'HEAD',
         resetExistingBranch: true,
-        reason: `hard_after dependencies already integrated: ${hardAfter.join(', ')}`,
+        reason: `pln#529: ${headNote('hard_after predecessors —')}`,
     };
 }
+/**
+ * @deprecated pln#529 — superseded by `resolveGatedLaneBase` (content + claim
+ * aware). Retained for callers that only have `(item, analysis)`; forwards using
+ * the analysis's done set for scope fallback (no claim access). Prefer the
+ * pre-computed `ReadyLane.worktreeBase`.
+ */
+export function selectWorktreeBaseForReadyLane(item, analysis, cwd = process.cwd()) {
+    const hardAfter = item.hard_after ?? [];
+    if (hardAfter.length === 0)
+        return {};
+    const donePlanIds = new Set(analysis.done.map((entry) => entry.planId));
+    if (!hardAfter.every((planId) => donePlanIds.has(planId)))
+        return {};
+    const itemByPlanId = new Map();
+    for (const entry of analysis.done)
+        itemByPlanId.set(entry.planId, entry);
+    return resolveGatedLaneBase(hardAfter, (predId) => itemByPlanId.get(predId)?.scope_hint ?? predId, cwd);
+}
 /**
  * Run a dispatch cycle: analyze the sequence, generate briefs, send assignments.
  */
@@ -654,7 +805,7 @@ export async function dispatch(options, cwd) {
         sweepAssignments(cwd, { actor: options.dispatcherAgent });
     }
     catch { /* best-effort */ }
-    const analysis = analyzeSequence(cwd);
+    const analysis = analyzeSequence(cwd, options.sequenceId);
     if (!analysis)
         return null;
     const result = { delivery_plan: [], messages_sent: [], commands: [], skipped: [], warnings: [] };
@@ -728,7 +879,10 @@ export async function dispatch(options, cwd) {
         let claimId = '(dry-run)';
         let worktreePath;
         if (!options.dryRun) {
-            const worktreeBase = selectWorktreeBaseForReadyLane(readyItem.item, analysis);
+            // pln#529 — use the content-aware base resolved during analyzeSequence
+            // (HEAD when the socle is integrated, else the predecessor branch). Fall
+            // back to a fresh resolution for direct callers that bypassed analyze.
+            const worktreeBase = readyItem.worktreeBase ?? selectWorktreeBaseForReadyLane(readyItem.item, analysis, cwd);
             const claimResult = createCoordinatorClaim({
                 agent: targetAgent,
                 scope: claimScope,

package/dist/core/execution-adapters.js

@@ -5,13 +5,39 @@ import { buildClaimEnvPrefix, buildWorkerIdentityEnv } from './execution-profile
 import { getCapabilityProfile } from './agent-capability.js';
 import { nowISO } from './ids.js';
 import { ensureRuntimeDirs, getRuntimeLogPath, getRuntimeSignalPath, } from './runtime-signals.js';
-export function buildAckWrapCommand(bashCommand, paths, isWin32) {
+// The turn-echo values are raw-embedded into a shell one-liner (see marker()),
+// so the `[A-Za-z0-9_-]` safety invariant documented on TurnEcho is LOAD-BEARING,
+// not cosmetic. A stray `"` desyncs cmd.exe quote-parity (no sentinel file is
+// written → the turn-owned run never converges under read-strict acceptance —
+// exactly the §13 D2 non-convergence this feature prevents); a `'` breaks out of
+// the POSIX `printf '…'` wrapper. All real sources (deriveTurnId/deriveChildIds
+// hex, crypto.randomUUID nonce) satisfy it, so this guard never fires in
+// production — it exists to turn a future out-of-class caller's SILENT corruption
+// into a loud, fast failure at the embed site.
+const TURN_ECHO_SAFE = /^[A-Za-z0-9_-]+$/;
+export function buildAckWrapCommand(bashCommand, paths, isWin32, turnEcho) {
+    if (turnEcho) {
+        for (const [field, value] of Object.entries(turnEcho)) {
+            if (!TURN_ECHO_SAFE.test(value)) {
+                throw new Error(`buildAckWrapCommand: turnEcho.${field} must match ${TURN_ECHO_SAFE} to be shell-safe for the completion sentinel (got ${JSON.stringify(value)})`);
+            }
+        }
+    }
     const touch = isWin32
         ? (p) => `type nul > "${p}"`
         : (p) => `touch "${p}"`;
+    // completed/failed marker: a turn-keyed JSON body when turnEcho is present,
+    // else the legacy empty touch (byte-for-byte unchanged for non-turn-owned
+    // spawns — full back-compat).
+    const marker = (p, status) => {
+        if (!turnEcho)
+            return touch(p);
+        const body = JSON.stringify({ turn_id: turnEcho.turn_id, run_id: turnEcho.run_id, nonce: turnEcho.nonce, status });
+        return isWin32 ? `echo ${body}>"${p}"` : `printf '%s' '${body}' > "${p}"`;
+    };
     const redirected = `${bashCommand} > "${paths.stdoutLog}" 2> "${paths.stderrLog}"`;
     return (`${touch(paths.ackPath)} && ` +
-        `( ${redirected} && ${touch(paths.completedPath)} || ${touch(paths.failedPath)} )`);
+        `( ${redirected} && ${marker(paths.completedPath, 'completed')} || ${marker(paths.failedPath, 'failed')} )`);
 }
 /**
  * Check if a binary is resolvable on the system PATH.
@@ -148,7 +174,7 @@ export class CliExecutionAdapter {
                 failedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'failed'),
                 stdoutLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stdout'),
                 stderrLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stderr'),
-            }, isWin32);
+            }, isWin32, options.turnEcho);
             child = spawn(wrappedCmd, [], {
                 detached: !isWin32,
                 shell: true,

package/dist/core/facade-schema.js

@@ -167,6 +167,26 @@ export const NextActionSchema = z.object({
     /** When this action applies, e.g. "when implementation is complete". */
     when: z.string().optional(),
 });
+/**
+ * pln#635 — structured warning. ADDITIVE sibling of `warnings: string[]`, which
+ * keeps its type and its exact historical contents (the legacy string is
+ * derived from this record — see core/warnings.ts). Five handler sites were
+ * already encoding structure into a string via JSON.stringify because there was
+ * nowhere else to put it; this is that nowhere.
+ *
+ * `next_actions` is what the string channel could never carry: the recovery
+ * path. A warning an agent cannot act on is just noise it learns to skip.
+ */
+export const WarningDetailSchema = z.object({
+    /** Stable machine-readable identifier, e.g. "scope_already_claimed". */
+    code: z.string(),
+    /** Human-readable prose. Also the legacy string for non-JSON codes. */
+    message: z.string(),
+    /** Structured payload (ids, agents, scopes) the prose mentions. */
+    data: z.record(z.string(), z.unknown()).optional(),
+    /** How to resolve it — same contract as the response-level next_actions. */
+    next_actions: z.array(NextActionSchema).optional(),
+});
 export const FacadeResponseSchema = z.object({
     status: z.enum(['ok', 'error', 'partial']),
     intent: z.string(),
@@ -222,6 +242,18 @@ export const FacadeResponseSchema = z.object({
      * remains for the bootstrap hint; new consumers should read this array.
      */
     next_actions: z.array(NextActionSchema).optional(),
+    /**
+     * pln#635 — structured warnings carrying a stable `code`, the `data` the prose
+     * refers to, and the recovery `next_actions`. Optional and additive:
+     * `warnings` keeps byte-identical contents, so a consumer ignoring this field
+     * is unaffected.
+     *
+     * This is a structured **SUBSET**, not a mirror — `warnings` remains the
+     * complete channel (see core/warnings.ts for why: handlers thread the string
+     * array into helpers by reference). Read `warnings` for completeness; read
+     * `warning_details` for the codes that carry a recovery path.
+     */
+    warning_details: z.array(WarningDetailSchema).optional(),
     /**
      * Code Map P0 (spec §10): opt-in, present ONLY when the project's Code Map
      * manifest carries `code_map_enabled: true`. Absent for every project that

package/dist/core/guidance-telemetry.js

@@ -0,0 +1,197 @@
+/**
+ * pln#634 PR2 — guidance adherence telemetry.
+ *
+ * brainclaw emits `next_actions` and `warning_details[].next_actions` on more and
+ * more surfaces (PR1, pln#635) but has never measured whether an agent's NEXT
+ * call follows the suggestion. Without that number the whole guidance backlog
+ * (pln#636/#637/#638) is prioritised on opinion: we cannot tell "the signal is
+ * missing" from "the signal is ignored", and those two diagnoses have opposite
+ * remedies — add more channels vs. stop adding channels and converge state
+ * server-side instead.
+ *
+ * MECHANISM. `executeMcpToolCall` is the single seam every MCP call passes
+ * through. After a response is built we remember which tools it suggested; on
+ * the next call in the same session we compare. One observation per
+ * suggestion→call pair.
+ *
+ * WHAT IS RECORDED: tool NAMES and a timestamp. Never arguments, never content,
+ * never file paths — the adherence question needs no payload, and a telemetry
+ * file that accumulated payloads would become a redaction problem
+ * (trp_0d79711e). This is also why it is safe to keep on by default.
+ *
+ * COST. Observations accumulate in memory and flush in batches, so a session of
+ * N calls costs ~N/BATCH writes rather than N. No daemon, no store mutation, no
+ * journal noise: the file lives beside the other machine-local runtime
+ * artifacts (ack/log sentinels).
+ *
+ * Opt out with `BRAINCLAW_GUIDANCE_TELEMETRY=0` (also false/off/no).
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { MEMORY_DIR } from './io.js';
+const TELEMETRY_FILE = 'guidance-adherence.jsonl';
+/** Flush every N observations — bounds writes without risking much on a crash. */
+const FLUSH_EVERY = 20;
+/** Rotate past this size so the file cannot grow without bound. */
+const MAX_BYTES = 512 * 1024;
+/** Per-session pending suggestion. Process-scoped: one MCP server per connection. */
+const pending = new Map();
+/** Buffered observations awaiting flush, keyed by target store cwd. */
+const buffered = new Map();
+function enabled() {
+    const raw = process.env.BRAINCLAW_GUIDANCE_TELEMETRY?.trim().toLowerCase();
+    return !(raw === '0' || raw === 'false' || raw === 'off' || raw === 'no');
+}
+function sessionKey(sessionId) {
+    return sessionId?.trim() || 'no-session';
+}
+/**
+ * Pull suggested tool names out of a built response.
+ *
+ * Deliberately a SHALLOW scan of the two places affordances actually live —
+ * top level (handlers that spread fields into `toolResponse`) and
+ * `structuredContent` (facade responses) — plus the per-warning nests. A deep
+ * recursive walk would cost more than the signal is worth and would pick up
+ * unrelated `next_actions` echoed inside payload data.
+ */
+export function extractSuggestedTools(response) {
+    if (!response || typeof response !== 'object')
+        return [];
+    const tools = [];
+    const collect = (value) => {
+        if (!Array.isArray(value))
+            return;
+        for (const entry of value) {
+            if (entry && typeof entry === 'object' && typeof entry.tool === 'string') {
+                tools.push(entry.tool);
+            }
+        }
+    };
+    const collectWarningNests = (value) => {
+        if (!Array.isArray(value))
+            return;
+        for (const entry of value) {
+            if (entry && typeof entry === 'object')
+                collect(entry.next_actions);
+        }
+    };
+    const top = response;
+    collect(top.next_actions);
+    collectWarningNests(top.warning_details);
+    const structured = top.structuredContent;
+    if (structured && typeof structured === 'object') {
+        const inner = structured;
+        collect(inner.next_actions);
+        collectWarningNests(inner.warning_details);
+    }
+    return [...new Set(tools)];
+}
+/**
+ * Observe a tool call against the suggestion left by the previous call.
+ *
+ * Returns the observation (for tests) or undefined when there was nothing
+ * pending. Consuming the pending entry is intentional: one suggestion set is
+ * judged exactly once, by the call that immediately follows it.
+ */
+export function observeToolCall(input) {
+    if (!enabled())
+        return undefined;
+    const key = sessionKey(input.sessionId);
+    const prior = pending.get(key);
+    if (!prior)
+        return undefined;
+    pending.delete(key);
+    const observation = {
+        at: input.now ?? new Date().toISOString(),
+        suggested_by: prior.suggestedBy,
+        suggested: prior.suggested,
+        called: input.tool,
+        followed: prior.suggested.includes(input.tool),
+    };
+    const list = buffered.get(input.cwd) ?? [];
+    list.push(observation);
+    buffered.set(input.cwd, list);
+    if (list.length >= FLUSH_EVERY)
+        flushAdherence(input.cwd);
+    return observation;
+}
+/** Remember what a response suggested, so the next call can be judged. */
+export function recordSuggestion(input) {
+    if (!enabled())
+        return;
+    const key = sessionKey(input.sessionId);
+    if (input.suggested.length === 0) {
+        // No suggestion means nothing to judge — clear rather than leave a stale
+        // set that a later call would be measured against unfairly.
+        pending.delete(key);
+        return;
+    }
+    pending.set(key, { suggestedBy: input.tool, suggested: input.suggested });
+}
+function telemetryPath(cwd) {
+    return path.join(cwd, MEMORY_DIR, 'coordination', 'runtime', TELEMETRY_FILE);
+}
+/** Write buffered observations. Best-effort by construction: never throws. */
+export function flushAdherence(cwd) {
+    const list = buffered.get(cwd);
+    if (!list || list.length === 0)
+        return;
+    buffered.set(cwd, []);
+    try {
+        const file = telemetryPath(cwd);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        try {
+            if (fs.statSync(file).size > MAX_BYTES) {
+                // Keep the newest half; adherence is a trend, not an archive.
+                const kept = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
+                fs.writeFileSync(file, kept.slice(Math.floor(kept.length / 2)).join('\n') + '\n', 'utf-8');
+            }
+        }
+        catch { /* absent file — nothing to rotate */ }
+        fs.appendFileSync(file, list.map((o) => JSON.stringify(o)).join('\n') + '\n', 'utf-8');
+    }
+    catch {
+        /* telemetry must never break a tool call */
+    }
+}
+/** Read the recorded observations and summarise. Never throws. */
+export function readAdherence(cwd) {
+    let persisted = [];
+    try {
+        persisted = fs.readFileSync(telemetryPath(cwd), 'utf-8')
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        /* absent or unreadable — an empty history, not an error */
+    }
+    // Include anything still buffered so a read right after a call is not stale.
+    const observations = [...persisted, ...(buffered.get(cwd) ?? [])];
+    const followed = observations.filter((o) => o.followed).length;
+    const perTool = new Map();
+    for (const o of observations) {
+        const entry = perTool.get(o.suggested_by) ?? { total: 0, followed: 0 };
+        entry.total += 1;
+        if (o.followed)
+            entry.followed += 1;
+        perTool.set(o.suggested_by, entry);
+    }
+    return {
+        total: observations.length,
+        followed,
+        ignored: observations.length - followed,
+        ...(observations.length > 0 ? { rate: followed / observations.length } : {}),
+        by_tool: [...perTool.entries()]
+            .map(([tool, v]) => ({ tool, total: v.total, followed: v.followed, rate: v.followed / v.total }))
+            .sort((a, b) => a.rate - b.rate),
+    };
+}
+/** Test hook — the maps are process-scoped by design. */
+export function __resetAdherenceForTests() {
+    pending.clear();
+    buffered.clear();
+}
+//# sourceMappingURL=guidance-telemetry.js.map