brainclaw 1.13.0 → 1.14.0

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/schema.js

@@ -1367,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),
@@ -1398,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'),

package/dist/core/worktree.js

@@ -229,6 +229,45 @@ function runGit(args, cwd, timeoutMs = GIT_QUERY_TIMEOUT_MS) {
         stderr: result.stderr ?? '',
     };
 }
+/**
+ * Resolve the real git worktree root for `cwd` (pln#614). On an IN-TREE project
+ * — a project dir that sits inside a larger repo (monorepo), where the git root
+ * is an ancestor, not the project dir itself — `git worktree add` MUST run from
+ * the true toplevel, and the per-project worktree hash MUST be derived from it.
+ *
+ * The bug (trp_28025248, cross-machine dogfooding 1.13.0): the assign/review
+ * claim path passed the project cwd straight to createWorktree, so `git worktree
+ * add` ran from the project dir and — with an empty `.git` left by the embedded
+ * init — failed with "not a git repository", while the ideation path (which
+ * resolved the toplevel) worked. resolveGitToplevel makes both paths agree.
+ *
+ * Falls back to the input cwd when `git rev-parse` cannot resolve a toplevel
+ * (not a repo, git absent) so non-git callers and tests keep their behaviour.
+ */
+export function resolveGitToplevel(cwd) {
+    // Codex review of PR #49 (HIGH): a stale/empty `.git` INSIDE the project dir
+    // (left by the embedded init — the exact leazzy case) makes `git rev-parse
+    // --show-toplevel` FAIL at that level instead of discovering the parent repo:
+    // git stops at the invalid gitdir. A plain fallback-to-cwd would then still
+    // run from the project dir and hash the subdir — the bug unfixed. So on
+    // failure we walk UP and retry from each ancestor, skipping past the invalid
+    // nested gitdir until a real toplevel is found; only a truly non-git tree
+    // falls back to the input cwd.
+    let dir = path.resolve(cwd);
+    for (let depth = 0; depth < 64; depth += 1) {
+        const result = runGit(['rev-parse', '--show-toplevel'], dir);
+        if (result.ok) {
+            const top = result.stdout.trim();
+            if (top)
+                return path.resolve(top);
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // filesystem root — not inside any repo
+        dir = parent;
+    }
+    return cwd;
+}
 /**
  * Returns true if the given path is a bare git repository.
  * Bare repos have no working tree, so worktree add is not applicable.
@@ -444,6 +483,12 @@ export function findWorktreePathForBranch(worktrees, branchName) {
  * Returns the absolute path to the newly created worktree.
  */
 export function createWorktree(mainWorktreePath, branchName, options = {}) {
+    // pln#614: resolve the true git toplevel first, so an in-tree project (project
+    // dir ≠ git root) creates its worktree from the real repo root — `git worktree
+    // add` runs there, and the per-project worktree hash (resolveWorktreePath) is
+    // derived from it, matching the ideation path. All git commands + the hash
+    // below use this resolved root rather than the raw project cwd.
+    mainWorktreePath = resolveGitToplevel(mainWorktreePath);
     const symlinkWarnings = [];
     const trySymlinkSharedPath = (entryName) => {
         const sourcePath = path.join(mainWorktreePath, entryName);
@@ -1048,6 +1093,10 @@ export function isBranchMergedByContent(mainWorktreePath, branchName, baseRef =
  */
 export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
     const result = { removed: [], skipped: [], pruned: false };
+    // pln#614: resolve the toplevel so an in-tree project scans the same
+    // per-project worktree hash createWorktree wrote under (and runs git from the
+    // real repo root).
+    mainWorktreePath = resolveGitToplevel(mainWorktreePath);
     // First prune stale git worktree admin entries
     pruneWorktrees(mainWorktreePath);
     result.pruned = true;
@@ -1147,6 +1196,9 @@ export function gcWorktreeIfHarvested(mainWorktreePath, worktreePath, options =
     });
     if (!worktreePath || !fs.existsSync(worktreePath))
         return out(false, 'already gone');
+    // pln#614: the merge-base / patch-id probes below run from the main repo — an
+    // in-tree project dir (empty .git) would fail them; resolve the real toplevel.
+    mainWorktreePath = resolveGitToplevel(mainWorktreePath);
     if (workerLooksAlive(worktreePath, options.livenessWindowMs ?? WORKTREE_GC_LIVENESS_WINDOW_MS)) {
         return out(false, 'worker still active (recent heartbeat)');
     }

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.13.0 on 2026-07-04T20:40:39.712Z
+// Source: brainclaw v1.14.0 on 2026-07-05T13:38:40.276Z
 export const FACTS = {
-  "version": "1.13.0",
-  "generated_at": "2026-07-04T20:40:39.712Z",
+  "version": "1.14.0",
+  "generated_at": "2026-07-05T13:38:40.276Z",
   "tools": {
     "count": 67,
     "published_count": 66,
@@ -472,7 +472,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-04T20:40:37.627Z",
+    "generated_at": "2026-07-05T13:38:38.216Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +481,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 78,
+        "duration_ms_median": 72,
         "payload_chars_median": 1650,
         "payload_tokens_est_median": 413
       },
@@ -489,7 +489,7 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 130,
+        "duration_ms_median": 126,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.13.0",
-  "generated_at": "2026-07-04T20:40:39.712Z",
+  "version": "1.14.0",
+  "generated_at": "2026-07-05T13:38:40.276Z",
   "tools": {
     "count": 67,
     "published_count": 66,
@@ -470,7 +470,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-04T20:40:37.627Z",
+    "generated_at": "2026-07-05T13:38:38.216Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -479,7 +479,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 78,
+        "duration_ms_median": 72,
         "payload_chars_median": 1650,
         "payload_tokens_est_median": 413
       },
@@ -487,7 +487,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 130,
+        "duration_ms_median": 126,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },