brainclaw 1.12.0 → 1.14.0

package/dist/core/entity-operations.js

@@ -15,7 +15,7 @@ import path from 'node:path';
 import { loadState, mutateState } from './state.js';
 import { archiveCandidate, listCandidates, loadCandidate, saveCandidate, } from './candidates.js';
 import { addCrossProjectLink, removeCrossProjectLink, resolveCrossProjectLinks, } from './cross-project.js';
-import { listClaims, loadClaim, saveClaim } from './claims.js';
+import { findActiveClaimsForPlan, listClaims, loadClaim, logCascadeReleaseResult, markClaimStale, releaseClaimsCascade, releaseClaimWithCascade, saveClaim, } from './claims.js';
 import { listActionRequired } from './actions.js';
 import { deleteAssignment, listAssignments, loadAssignment, saveAssignment, transitionAssignment } from './assignments.js';
 import { listAgentRuns } from './agentruns.js';
@@ -599,8 +599,7 @@ export function removeEntity(name, id, cwd, purge = false) {
             throw new EntityOperationUnsupportedError(name, 'remove');
     }
 }
-// ─── TRANSITION ───────────────────────────────────────────────────────
-export function transitionEntity(name, id, to, cwd, _reason) {
+export function transitionEntity(name, id, to, cwd, _reason, auth) {
     const spec = ENTITY_REGISTRY[name];
     if (!spec.statusField) {
         throw new Error(`${name} has no lifecycle (statusField is undefined)`);
@@ -619,6 +618,32 @@ export function transitionEntity(name, id, to, cwd, _reason) {
     switch (name) {
         case 'plan': {
             updatePlan({ id, status: to }, cwd);
+            // trp#928 — implement the `release_linked_claims_if_last` cascade tag.
+            // Before this landing the tag was advertised by the entity registry but
+            // the imperative cascade never ran, so a plan closed while its worker
+            // claims stayed active (ghost claims). The cascade now:
+            //  - runs only on plan → done (the tag's actual trigger)
+            //  - releases each active claim linked via plan_id
+            //  - LOGS per claim (released / skipped+reason / error) via the runtime
+            //    event journal so `bclaw_find(entity=agent_run)` and dashboards can
+            //    observe silent ownership failures instead of guessing at them.
+            // Ownership check: this path runs from bclaw_transition, so it inherits
+            // the caller's TransitionAuth (populated for entity='claim' but not for
+            // entity='plan'). auth undefined = system convergence (bypass ownership),
+            // matching the historical implicit contract for plan cascades.
+            if (to === 'done') {
+                const linked = findActiveClaimsForPlan(id, cwd);
+                if (linked.length > 0) {
+                    const cascade = releaseClaimsCascade(linked.map((c) => c.id), { cwd });
+                    logCascadeReleaseResult({
+                        actor: 'system',
+                        trigger: 'plan_done',
+                        plan_id: id,
+                        cascade,
+                        cwd,
+                    });
+                }
+            }
             return { entity: name, id, from, to, side_effects: sideEffects };
         }
         case 'decision':
@@ -656,6 +681,29 @@ export function transitionEntity(name, id, to, cwd, _reason) {
             updateSequence({ id, status: to }, cwd);
             return { entity: name, id, from, to, side_effects: sideEffects };
         }
+        case 'claim': {
+            // trp#928 — the entity registry advertised `active → released|stale` but
+            // transitionEntity never routed for entity=claim. The isValidTransition
+            // check above passed for anyone calling `bclaw_transition(entity='claim',
+            // to='released')`, but the transition then fell through to the
+            // EntityOperationUnsupportedError default. Now: released hits the same
+            // cascade path bclaw_release_claim uses (audit + plan-done cascade); stale
+            // uses markClaimStale (audit + `stale` terminal status). Reuses ReleaseClaimAuth
+            // so a trusted+ coordinator can release across ownership with override.
+            const releaseAuth = auth
+                ? { agent: auth.agent, agent_id: auth.agent_id, session_id: auth.session_id, override: auth.override }
+                : undefined;
+            if (to === 'released') {
+                releaseClaimWithCascade(id, { planStatus: _reason === 'done' ? 'done' : undefined, cwd, auth: releaseAuth });
+                return { entity: name, id, from, to, side_effects: sideEffects };
+            }
+            if (to === 'stale') {
+                markClaimStale(id, cwd, releaseAuth);
+                return { entity: name, id, from, to, side_effects: sideEffects };
+            }
+            // isValidTransition already excluded every other target — belt-and-braces:
+            throw new InvalidTransitionError(name, from, to);
+        }
         default:
             throw new EntityOperationUnsupportedError(name, 'transition', `Lifecycle transitions for ${name} not yet wired.`);
     }

package/dist/core/gc-semantic.js

@@ -543,6 +543,85 @@ export function enforceRuntimeNoteRetention(options = {}) {
     result.backup_path = backupPath;
     return result;
 }
+/**
+ * pln#602 — park closed auto-generated handoffs older than the cutoff.
+ *
+ * The stale-warning surface counts every open handoff older than 14d as
+ * something the agent should act on. Once a handoff is `closed` (accepted +
+ * fulfilled OR explicitly retired), it stops being a workflow signal and
+ * starts being noise: the fable-audit trace repeatedly rendered fully-served
+ * handoffs from months prior. Park them next to the released-claims archive
+ * (same JSONL + backup pattern) so `bclaw_find` still surfaces them on demand
+ * but the compact bclaw_work context can move on.
+ *
+ * Auto-generated detection matches the same "Session sess_ … auto-generated
+ * handoff" prefix that `dedupAutoHandoffs` uses — human-authored handoffs
+ * stay put regardless of age (they may carry decisions the agent needs).
+ */
+export function parkClosedAutoHandoffs(cwd, minAgeDays = DEFAULT_MIN_AGE_DAYS, dryRun = false) {
+    const cutoff = new Date(Date.now() - minAgeDays * 24 * 60 * 60 * 1000).toISOString();
+    const handoffsDir = path.join(cwd, '.brainclaw', 'coordination', 'handoffs');
+    if (!fs.existsSync(handoffsDir))
+        return { candidates: 0, parked: 0 };
+    const eligible = [];
+    const files = fs.readdirSync(handoffsDir).filter((f) => f.endsWith('.json'));
+    for (const file of files) {
+        const filePath = path.join(handoffsDir, file);
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const parsed = JSON.parse(content);
+            const status = typeof parsed.status === 'string' ? parsed.status : '';
+            if (status !== 'closed')
+                continue;
+            const text = typeof parsed.text === 'string' ? parsed.text : '';
+            const isAutoGenerated = text.startsWith('Session sess_') && text.includes('auto-generated handoff');
+            if (!isAutoGenerated)
+                continue;
+            const updatedAt = typeof parsed.updated_at === 'string' ? parsed.updated_at
+                : typeof parsed.created_at === 'string' ? parsed.created_at : '';
+            if (!updatedAt || updatedAt > cutoff)
+                continue;
+            eligible.push({ filePath, content });
+        }
+        catch {
+            // Skip unparseable — a separate check (loadDirectoryItems) will surface it.
+        }
+    }
+    if (dryRun || eligible.length === 0) {
+        return { candidates: eligible.length, parked: 0 };
+    }
+    const archivePath = path.join(handoffsDir, 'compacted.jsonl');
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = path.join(cwd, '.brainclaw', 'gc-backups', `compact-handoffs-closed-${timestamp}.jsonl`);
+    fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+    let parked = 0;
+    for (const { filePath, content } of eligible) {
+        // Codex PR#48 finding 4: order the steps so a partial failure can never
+        // leave the source on disk AND its record already in the compaction log
+        // (which produced a duplicate compacted record on the next pass). The safe
+        // order is backup → unlink → archive:
+        //   1. backup first  — park-don't-delete safety net is written before any
+        //      removal, so the raw handoff is always recoverable.
+        //   2. unlink next    — if this throws, we do NOT archive, so no compacted
+        //      record exists for a source that is still present → no duplicate.
+        //   3. archive last   — if this throws after a successful unlink, the source
+        //      is gone (in the backup) and simply absent from compacted.jsonl; the
+        //      next pass cannot re-see it, so still no duplicate.
+        try {
+            const parsed = JSON.parse(content);
+            parsed._compacted_at = new Date().toISOString();
+            parsed._compaction_type = 'closed-auto-handoff';
+            fs.appendFileSync(backupPath, content.trim() + '\n', 'utf-8');
+            fs.unlinkSync(filePath);
+            fs.appendFileSync(archivePath, JSON.stringify(parsed) + '\n', 'utf-8');
+            parked += 1;
+        }
+        catch (err) {
+            logger.debug('parkClosedAutoHandoffs: failed to park', err);
+        }
+    }
+    return { candidates: eligible.length, parked, backup_path: backupPath };
+}
 /**
  * Deduplicate auto-generated session-end handoffs. These carry the same
  * commits list when several sessions close on the same project state, so the

package/dist/core/hint-aging.js

@@ -0,0 +1,188 @@
+/**
+ * Serve-count aging for stale_warnings + workflow_hints (pln#602).
+ *
+ * Empirical driver: fable-audit-2026-07 opened with three stale_warnings from
+ * 87 days ago (pln_0e4a848b, rtn_d5a940c3, rtn_5eb68c9e) rendered in full at
+ * every session, plus a workflow_hint "confirm or retire dec_426b3b00" served
+ * on repeat for months. Agents learn to skim past that noise — which is
+ * exactly the reflex we cannot afford.
+ *
+ * Contract: an entry is served in detail `k` times, then folded into a single
+ * aggregate line that carries the exact next_action (`bclaw_find …`) so the
+ * agent still has one clear pointer. The counter is a small JSON file, safe to
+ * lose — hitting it twice per stale item is worse than losing it once, and a
+ * missing file just resets counts to zero.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveEntityDir } from './io.js';
+import { logger } from './logger.js';
+import { loadHygienePolicy } from './hygiene-policy.js';
+function makeEmptyRegistry() {
+    return { schema_version: 1, warnings: {}, hints: {} };
+}
+function registryFile(cwd) {
+    const dir = resolveEntityDir('coordination/hygiene', cwd, 'write');
+    return path.join(dir, 'serve-counter.json');
+}
+export function loadServeRegistry(cwd) {
+    const root = cwd ?? process.cwd();
+    const file = registryFile(root);
+    if (!fs.existsSync(file))
+        return makeEmptyRegistry();
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        return {
+            schema_version: 1,
+            warnings: parsed.warnings ?? {},
+            hints: parsed.hints ?? {},
+        };
+    }
+    catch (err) {
+        logger.debug('hint-aging: failed to read serve counter, resetting', err);
+        return makeEmptyRegistry();
+    }
+}
+export function saveServeRegistry(registry, cwd) {
+    const root = cwd ?? process.cwd();
+    const file = registryFile(root);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(registry, null, 2), 'utf-8');
+    }
+    catch (err) {
+        logger.debug('hint-aging: failed to write serve counter', err);
+    }
+}
+function bump(counter, nowIso) {
+    if (!counter)
+        return { count: 1, first_at: nowIso, last_at: nowIso };
+    return { count: counter.count + 1, first_at: counter.first_at, last_at: nowIso };
+}
+/**
+ * Fold stale warnings served ≥ k times into a single aggregate line. The
+ * aggregate carries a bclaw_find pointer so the agent still has one exact
+ * next-action instead of guessing which filter to use.
+ *
+ * Idempotence: calling with recordServe=false is pure — the returned split is
+ * derived from the current registry alone. With recordServe=true the counter
+ * bumps by one per warning ID in `warnings`, and folded_ids may grow on the
+ * NEXT call as items cross the threshold.
+ */
+export function ageStaleWarnings(warnings, cwd, options = {}) {
+    const policy = options.policy ?? loadHygienePolicy(cwd);
+    if (policy.disabled) {
+        return { warnings, served_ids: [], folded_ids: [] };
+    }
+    const registry = options.registry ?? loadServeRegistry(cwd);
+    const nowIso = new Date(options.nowMs ?? Date.now()).toISOString();
+    const k = policy.stale_warning_serve_k;
+    const detail = [];
+    const folded = [];
+    const served_ids = [];
+    const folded_ids = [];
+    for (const w of warnings) {
+        const existing = registry.warnings[w.id];
+        const seenCount = existing?.count ?? 0;
+        if (seenCount >= k) {
+            folded.push(w);
+            folded_ids.push(w.id);
+        }
+        else {
+            detail.push(w);
+            served_ids.push(w.id);
+            if (options.recordServe !== false) {
+                registry.warnings[w.id] = bump(existing, nowIso);
+            }
+        }
+    }
+    if (options.recordServe !== false && served_ids.length > 0 && cwd !== undefined) {
+        saveServeRegistry(registry, cwd);
+    }
+    let aggregate;
+    if (folded.length > 0) {
+        const byEntity = new Map();
+        for (const w of folded)
+            byEntity.set(w.entity, (byEntity.get(w.entity) ?? 0) + 1);
+        const parts = [...byEntity.entries()].map(([entity, n]) => `${n} ${entity}${n === 1 ? '' : 's'}`);
+        aggregate = `${folded.length} stale item${folded.length === 1 ? '' : 's'} you've already been offered (${parts.join(', ')}) — bclaw_find(status:'stale') to review, or bclaw_transition to retire.`;
+    }
+    return { warnings: detail, aggregate, served_ids, folded_ids };
+}
+/**
+ * Fold workflow hints served ≥ k times. Hints have no stable ID — we key on
+ * their normalised text so the same "confirm or retire dec_426b3b00" line
+ * folds even across sessions.
+ */
+export function ageWorkflowHints(hints, cwd, options = {}) {
+    const policy = options.policy ?? loadHygienePolicy(cwd);
+    if (policy.disabled) {
+        return { hints, served_ids: [], folded_ids: [] };
+    }
+    const registry = options.registry ?? loadServeRegistry(cwd);
+    const nowIso = new Date(options.nowMs ?? Date.now()).toISOString();
+    const k = policy.workflow_hint_serve_k;
+    const detail = [];
+    const folded = [];
+    const served_ids = [];
+    const folded_ids = [];
+    for (const h of hints) {
+        const key = hintKey(h);
+        const existing = registry.hints[key];
+        const seenCount = existing?.count ?? 0;
+        if (seenCount >= k) {
+            folded.push(h);
+            folded_ids.push(key);
+        }
+        else {
+            detail.push(h);
+            served_ids.push(key);
+            if (options.recordServe !== false) {
+                registry.hints[key] = bump(existing, nowIso);
+            }
+        }
+    }
+    if (options.recordServe !== false && served_ids.length > 0 && cwd !== undefined) {
+        saveServeRegistry(registry, cwd);
+    }
+    let aggregate;
+    if (folded.length > 0) {
+        aggregate = `${folded.length} workflow hint${folded.length === 1 ? '' : 's'} you've already been offered — bclaw_context(kind:'workflow_hints') to review.`;
+    }
+    return { hints: detail, aggregate, served_ids, folded_ids };
+}
+/**
+ * Normalise a workflow-hint text into a stable key. The generator interpolates
+ * counts and IDs, so keying on the raw text would give every "3 in-progress
+ * plan(s)…" variant its own counter. Strip digits and known ID prefixes.
+ */
+function hintKey(text) {
+    return text
+        .replace(/\d+/g, '#')
+        .replace(/\b(pln|rtn|dec|trp|clm|asgn|sess|cnd|hnd|con)_[a-f0-9]{4,}\b/g, '$1_#')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+function median(nums) {
+    if (nums.length === 0)
+        return 0;
+    const sorted = [...nums].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+export function computeServeStats(counters, threshold) {
+    const values = Object.values(counters);
+    const counts = values.map((c) => c.count);
+    const first_ats = values.map((c) => c.first_at).sort();
+    return {
+        total: values.length,
+        over_threshold: counts.filter((c) => c >= threshold).length,
+        median_count: median(counts),
+        oldest_first_at: first_ats[0],
+    };
+}
+export const __testing = { hintKey };
+//# sourceMappingURL=hint-aging.js.map

package/dist/core/hygiene-policy.js

@@ -0,0 +1,77 @@
+/**
+ * Coordination-hygiene policy (pln#602).
+ *
+ * Family-level TTL + serve-count thresholds that govern the lazy sweep at the
+ * bclaw_work read path and the full sweep at session-start. Keeping the policy
+ * in one place lets `brainclaw doctor --hygiene` describe the current governance
+ * to operators without chasing constants across five modules.
+ *
+ * Design contract:
+ *   - **Park-don't-delete.** Every TTL crossing must transit through a canonical
+ *     grammar (transitionAssignment expired/timed_out, handoff archive) or write
+ *     a backup file before unlinking. No policy field toggles deletion.
+ *   - **Serve-count K is UX budget, not memory GC.** Once a stale_warning or
+ *     workflow_hint has been rendered `k` times we swap it for an aggregate
+ *     counter so the agent gets ONE actionable pointer instead of the same
+ *     three lines every session (fable-audit-2026-07 empirical evidence).
+ *   - **Opt-out means literally opt-out.** `disabled: true` bypasses BOTH the
+ *     sweep and the aging — archive stores that curate their own retention
+ *     stay in charge.
+ *
+ * @module
+ */
+import { loadConfig } from './config.js';
+import { logger } from './logger.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const DEFAULT_HYGIENE_POLICY = {
+    disabled: false,
+    assignment_offered_ttl_ms: 3 * DAY_MS,
+    assignment_accepted_ttl_ms: 1 * DAY_MS,
+    assignment_started_ttl_ms: 1 * DAY_MS,
+    handoff_closed_ttl_ms: 30 * DAY_MS,
+    stale_warning_serve_k: 3,
+    workflow_hint_serve_k: 3,
+    read_path_sweep_budget: 25,
+};
+/** The override keys HygieneConfigSchema declares — used to detect typos. */
+const HYGIENE_POLICY_KEYS = [
+    'disabled',
+    'assignment_offered_ttl_ms',
+    'assignment_accepted_ttl_ms',
+    'assignment_started_ttl_ms',
+    'handoff_closed_ttl_ms',
+    'stale_warning_serve_k',
+    'workflow_hint_serve_k',
+    'read_path_sweep_budget',
+];
+/**
+ * Best-effort load: any policy override is merged on top of the defaults.
+ * Config parse errors fall back silently to defaults so a broken config.yaml
+ * cannot break every bclaw_work call.
+ *
+ * `config.hygiene` is now declared by ConfigSchema (HygieneConfigSchema), so
+ * valid overrides survive the zod parse instead of being stripped (Codex review
+ * of PR #48, HIGH — the previous `as unknown as { hygiene? }` cast read a key
+ * the schema had already discarded, so `disabled`/TTL overrides never applied).
+ * Undefined fields (partial override or an unknown/typo sub-key that the schema
+ * stripped) fall back to DEFAULT_HYGIENE_POLICY; a typo is logged so the drop is
+ * not fully silent, consistent with the store-wide strip convention.
+ */
+export function loadHygienePolicy(cwd) {
+    try {
+        const config = loadConfig(cwd);
+        const overrides = config.hygiene ?? {};
+        for (const key of Object.keys(overrides)) {
+            if (!HYGIENE_POLICY_KEYS.includes(key)) {
+                logger.warn(`config.hygiene: unknown key "${key}" ignored (valid keys: ${HYGIENE_POLICY_KEYS.join(', ')})`);
+            }
+        }
+        // Drop undefined values so a partial override never overwrites a default with undefined.
+        const defined = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== undefined));
+        return { ...DEFAULT_HYGIENE_POLICY, ...defined };
+    }
+    catch {
+        return { ...DEFAULT_HYGIENE_POLICY };
+    }
+}
+//# sourceMappingURL=hygiene-policy.js.map

package/dist/core/loops/store.js

@@ -5,6 +5,7 @@ import { memoryDir, writeFileAtomic } from '../io.js';
 import { nowISO } from '../ids.js';
 import { logger } from '../logger.js';
 import { convergeAssignmentToTerminal, loadAssignment } from '../assignments.js';
+import { logCascadeReleaseResult, releaseClaimsCascade } from '../claims.js';
 import { gcWorktreeIfHarvested } from '../worktree.js';
 import { writeProjectMdSafe } from './hooks/bootstrap-write.js';
 import { notifyOperatorOnInputRequested } from './hooks/notify-operator.js';
@@ -435,6 +436,38 @@ export function closeLoop(input, cwd) {
         }
         catch { /* never block loop close on assignment convergence */ }
     }
+    // trp#928 — cascade-release claims linked to slots + slot-linked assignments.
+    // Before this landing, loop close converged the assignment lifecycle but left
+    // reviewer claims active indefinitely (dogfooding 2026-07: 23 ghost claims,
+    // most from closed review loops). System-actor release: no auth → the
+    // ownership check is skipped, matching convergeAssignmentToTerminal's contract
+    // above (loop close is a system action, not a user-driven release).
+    const claimIdsFromSlots = [];
+    for (const slot of next.slots) {
+        if (slot.claim_id)
+            claimIdsFromSlots.push(slot.claim_id);
+        if (slot.assignment_id) {
+            try {
+                const assignment = loadAssignment(slot.assignment_id, cwd);
+                if (assignment?.claim_id)
+                    claimIdsFromSlots.push(assignment.claim_id);
+            }
+            catch { /* assignment gone — skip */ }
+        }
+    }
+    if (claimIdsFromSlots.length > 0) {
+        try {
+            const cascade = releaseClaimsCascade(claimIdsFromSlots, { cwd });
+            logCascadeReleaseResult({
+                actor: input.actor,
+                trigger: 'loop_close',
+                loop_id: input.id,
+                cascade,
+                cwd,
+            });
+        }
+        catch { /* never block loop close on cascade release */ }
+    }
     // pln#594: GC the dispatched sub-agent worktrees now the loop is done, so
     // review/dispatch worktrees stop accumulating under ~/.brainclaw/worktrees/.
     // Only on a COMPLETED close — cancelled/blocked keep their worktree (+ run

package/dist/core/reputation.js

@@ -281,6 +281,24 @@ export function buildReputationSnapshot(cwd) {
         resume_weight: 0.35,
         mcp_exposure: false,
     };
+    // pln#578 — disabled reputation (the default) must not pay for the sweep.
+    // Every consumer already treats a disabled snapshot as empty: agents is []
+    // (line below gates on enabled), so ranking bonuses are 0 and the resume
+    // summary is undefined. Yet the full signal sweep (pending + archived
+    // candidates, all runtime notes, all claims, a complete loadState) was still
+    // running — two of the four full-store read passes a single buildContext
+    // performed on a large store. Exit before any store read when disabled.
+    if (!reputationConfig.enabled) {
+        return {
+            enabled: false,
+            visibility: reputationConfig.visibility,
+            window_days: reputationConfig.decay_days,
+            generated_at: nowISO(),
+            project_id: config.project_id,
+            current_agent_id: resolveCurrentAgentIdentity(cwd)?.agent_id,
+            agents: [],
+        };
+    }
     const registered = listAgentIdentities(cwd);
     const currentAgent = resolveCurrentAgentIdentity(cwd);
     const resolvers = buildIdentityResolvers(registered);

package/dist/core/schema.js

@@ -1122,6 +1122,13 @@ export const CurrentSessionStateSchema = z.object({
     branch: z.string().optional(),
     /** Isolation mode: shared-checkout (default) or dedicated-worktree. */
     isolation_mode: IsolationModeSchema.optional(),
+    /**
+     * True when the session was materialized by an auto-repair path (e.g. a
+     * canonical write arriving without a prior session). Tag lets aggressive
+     * harvesting distinguish worker-authored sessions from operator sessions
+     * (pln#602 lesson on the pln#578 887-file blowup).
+     */
+    auto_created: z.boolean().optional(),
 });
 export const MemorySeedKindSchema = z.enum([
     'command',
@@ -1360,6 +1367,27 @@ export const BrainclawLocalReleaseManifestSchema = z.object({
     release_notes: z.string().optional(),
     agent_release_notes: AgentReleaseNotesSchema.optional(),
 });
+/**
+ * Coordination-hygiene overrides (pln#602). Declared here so ConfigSchema does
+ * NOT strip the `hygiene` key at parse time — the earlier untyped read
+ * (`loadConfig() as { hygiene? }`) was silently unreachable because zod strips
+ * unknown keys by default (Codex review of PR #48, HIGH). Every field is an
+ * optional override on DEFAULT_HYGIENE_POLICY; the numeric TTLs/budgets are
+ * validated positive so a bad value fails loudly rather than disabling a sweep.
+ * Unknown sub-keys still follow the store-wide strip convention (a typo is
+ * ignored, consistent with reputation/governance/etc.) — the load path logs
+ * them via loadHygienePolicy so the drop is not fully silent.
+ */
+export const HygieneConfigSchema = z.object({
+    disabled: z.boolean().optional(),
+    assignment_offered_ttl_ms: z.number().int().positive().optional(),
+    assignment_accepted_ttl_ms: z.number().int().positive().optional(),
+    assignment_started_ttl_ms: z.number().int().positive().optional(),
+    handoff_closed_ttl_ms: z.number().int().positive().optional(),
+    stale_warning_serve_k: z.number().int().positive().optional(),
+    workflow_hint_serve_k: z.number().int().positive().optional(),
+    read_path_sweep_budget: z.number().int().positive().optional(),
+});
 export const ConfigSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     version: z.literal(1),
@@ -1391,6 +1419,7 @@ export const ConfigSchema = z.object({
     reflective_memory: ReflectiveMemoryConfigSchema.optional(),
     governance: GovernanceConfigSchema.optional(),
     reputation: ReputationConfigSchema.optional(),
+    hygiene: HygieneConfigSchema.optional(),
     agent_integrations: AgentIntegrationsConfigSchema.default({ declarations: [] }),
     cross_project_links: z.array(CrossProjectLinkSchema).optional().default([]),
     implicit_session_ttl: z.string().default('4h'),