@productbrain/cli 0.1.0-beta.1419 → 0.1.0-beta.14193

package/dist/lib/notice-marker.js

@@ -1,15 +1,28 @@
 /**
  * Once-per-session (agent) / once-per-day (human) notice claim via O_EXCL.
  * First process to create the marker wins (returns true => may print). All others,
- * and any error, fail OPEN to no-print (return false). Markers self-expire by key
- * (session id rotates per session; daily key rolls per UTC day). DEC-2.
+ * and any error, fail OPEN to no-print (return false). A per-marker O_EXCL lock
+ * serializes stale-marker eviction against that claim. Markers expire by key
+ * (session id rotates per session; daily key rolls per UTC day) and by age, except
+ * that a losing claim heartbeats the current marker so a renewed session survives
+ * the sweep. DEC-2.
  */
-import { openSync, closeSync, mkdirSync, statSync, readdirSync, unlinkSync } from 'node:fs';
+import { openSync, closeSync, existsSync, linkSync, mkdirSync, statSync, readdirSync, unlinkSync, utimesSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { readSession } from './session.js';
 const CONFIG_DIR = join(homedir(), '.config', 'productbrain');
+// Non-current session residue becomes stale after one server expiry lease. The
+// same ID can be renewed, so claimNotice heartbeats the locked current marker.
+// Lease source: convex/intelligence/agentSessions.ts MAX_SESSION_DURATION_MS.
+const SESSION_STALE_MS = 8 * 60 * 60 * 1000;
 const DAILY_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+// Lock actions contain only synchronous local filesystem calls. A one-minute
+// lease bounds crash residue while leaving ample headroom for a live holder.
+const LOCK_STALE_MS = 60 * 1000;
+const LOCK_PREFIX = '.notice-marker-lock-';
+const LOCK_RECLAIM_SUFFIX = '.reclaim';
+const LOCK_PIN_SUFFIX = '.target';
 function utcDateStamp() {
     const d = new Date();
     const p = (n) => String(n).padStart(2, '0');
@@ -23,28 +36,185 @@ function markerKey(channel) {
     // If no active session, fall back to a daily key so the per-day throttle still holds.
     return session?.sessionId ? `notice-session-${session.sessionId}` : `notice-agent-daily-${utcDateStamp()}`;
 }
-function cleanupOldNoticeMarkers() {
+function markerRetentionMs(name) {
+    if (name.startsWith('notice-session-'))
+        return SESSION_STALE_MS;
+    if (name.startsWith('notice-human-') || name.startsWith('notice-agent-daily-')) {
+        return DAILY_STALE_MS;
+    }
+    return null;
+}
+function markerLockPath(name) {
+    return join(CONFIG_DIR, `${LOCK_PREFIX}${name}`);
+}
+function cleanupStaleRecovery(lockPath, now) {
+    const reclaimPath = `${lockPath}${LOCK_RECLAIM_SUFFIX}`;
+    const pinPath = `${reclaimPath}${LOCK_PIN_SUFFIX}`;
+    try {
+        if (now - statSync(reclaimPath).mtimeMs <= LOCK_STALE_MS)
+            return;
+        try {
+            unlinkSync(pinPath);
+        }
+        catch { /* absent or unavailable identity pin */ }
+        unlinkSync(reclaimPath);
+        return;
+    }
+    catch { /* absent, fresh, or unavailable recovery election */ }
+    try {
+        if (now - statSync(pinPath).mtimeMs > LOCK_STALE_MS)
+            unlinkSync(pinPath);
+    }
+    catch { /* absent or unavailable orphan identity pin */ }
+}
+/**
+ * Reclaim one expired lock without a pathname-only unlink race. O_EXCL elects
+ * one reclaimer; its hard link pins the exact stale file instance to remove.
+ */
+function reclaimStaleLock(lockPath, now) {
+    const reclaimPath = `${lockPath}${LOCK_RECLAIM_SUFFIX}`;
+    const pinPath = `${reclaimPath}${LOCK_PIN_SUFFIX}`;
+    let reclaimFd;
+    let observed;
+    try {
+        observed = statSync(lockPath);
+        if (now - observed.mtimeMs <= LOCK_STALE_MS)
+            return false;
+        cleanupStaleRecovery(lockPath, now);
+        reclaimFd = openSync(reclaimPath, 'wx');
+        closeSync(reclaimFd);
+    }
+    catch {
+        return false;
+    }
+    try {
+        linkSync(lockPath, pinPath);
+        const pinned = statSync(pinPath);
+        if (observed.dev !== pinned.dev || observed.ino !== pinned.ino)
+            return false;
+        const current = statSync(lockPath);
+        if (current.dev !== pinned.dev || current.ino !== pinned.ino)
+            return false;
+        unlinkSync(lockPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            unlinkSync(pinPath);
+        }
+        catch { /* bounded by the next stale sweep */ }
+        try {
+            unlinkSync(reclaimPath);
+        }
+        catch { /* bounded by the next stale sweep */ }
+    }
+}
+function acquireMarkerLock(name) {
+    const lockPath = markerLockPath(name);
     try {
-        for (const name of readdirSync(CONFIG_DIR)) {
-            if (!name.startsWith('notice-human-') &&
-                !name.startsWith('notice-agent-daily-') &&
-                !name.startsWith('notice-session-'))
+        return openSync(lockPath, 'wx');
+    }
+    catch {
+        if (!reclaimStaleLock(lockPath, Date.now()))
+            return null;
+        try {
+            return openSync(lockPath, 'wx');
+        }
+        catch {
+            return null;
+        }
+    }
+}
+function withMarkerLock(name, action) {
+    const lockPath = markerLockPath(name);
+    const lockFd = acquireMarkerLock(name);
+    if (lockFd === null)
+        return null;
+    try {
+        closeSync(lockFd);
+        return action();
+    }
+    finally {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { /* best-effort lock release */ }
+    }
+}
+function cleanupAbandonedMarkerLocks(names, now) {
+    for (const name of names) {
+        if (!name.startsWith(LOCK_PREFIX))
+            continue;
+        if (name.endsWith(LOCK_RECLAIM_SUFFIX)) {
+            cleanupStaleRecovery(join(CONFIG_DIR, name.slice(0, -LOCK_RECLAIM_SUFFIX.length)), now);
+            continue;
+        }
+        if (name.endsWith(`${LOCK_RECLAIM_SUFFIX}${LOCK_PIN_SUFFIX}`))
+            continue;
+        const path = join(CONFIG_DIR, name);
+        try {
+            if (now - statSync(path).mtimeMs <= LOCK_STALE_MS)
                 continue;
-            const p = join(CONFIG_DIR, name);
-            if (Date.now() - statSync(p).mtimeMs > DAILY_STALE_MS)
-                unlinkSync(p);
+            reclaimStaleLock(path, now);
+        }
+        catch {
+            // Lock recovery is best-effort and isolated per file, like marker GC.
         }
     }
-    catch { /* best-effort */ }
+}
+function cleanupOldNoticeMarkers(currentName) {
+    let names;
+    try {
+        names = readdirSync(CONFIG_DIR);
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    cleanupAbandonedMarkerLocks(names, now);
+    for (const name of names) {
+        if (name === currentName)
+            continue;
+        const staleAfterMs = markerRetentionMs(name);
+        if (staleAfterMs === null)
+            continue;
+        withMarkerLock(name, () => {
+            try {
+                const p = join(CONFIG_DIR, name);
+                if (now - statSync(p).mtimeMs > staleAfterMs)
+                    unlinkSync(p);
+            }
+            catch {
+                // A marker can disappear or become unavailable while the sweep runs.
+                // Keep cleanup best-effort without skipping the remaining files.
+            }
+        });
+    }
 }
 /** Returns true exactly once per (channel, session/day). Never throws. */
 export function claimNotice(channel) {
-    const path = join(CONFIG_DIR, markerKey(channel));
+    const name = markerKey(channel);
+    const path = join(CONFIG_DIR, name);
     try {
         mkdirSync(CONFIG_DIR, { recursive: true });
-        closeSync(openSync(path, 'wx')); // 'wx' = O_EXCL: throws EEXIST if present
-        cleanupOldNoticeMarkers();
-        return true;
+        return withMarkerLock(name, () => {
+            cleanupOldNoticeMarkers(name);
+            if (existsSync(path)) {
+                // A live server session can be renewed under the same ID. Refreshing the
+                // marker on each suppressed notice keeps that active session out of GC.
+                try {
+                    const now = new Date();
+                    utimesSync(path, now, now);
+                }
+                catch { /* the existing claim still wins */ }
+                return false;
+            }
+            closeSync(openSync(path, 'wx')); // 'wx' = O_EXCL: throws EEXIST if present
+            return true;
+        }) ?? false;
     }
     catch {
         return false; // already claimed, or fs error => fail open to no-print

package/dist/lib/notice-marker.js.map

@@ -1 +1 @@
-{"version":3,"file":"notice-marker.js","sourceRoot":"","sources":["../../src/lib/notice-marker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC5F,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;AAC9D,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE/C,SAAS,YAAY;IACnB,MAAM,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC;IACrB,MAAM,CAAC,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpD,OAAO,GAAG,CAAC,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED,qFAAqF;AACrF,SAAS,SAAS,CAAC,OAA0B;IAC3C,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,gBAAgB,YAAY,EAAE,EAAE,CAAC;IACjE,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;IAC9B,sFAAsF;IACtF,OAAO,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,kBAAkB,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,sBAAsB,YAAY,EAAE,EAAE,CAAC;AAC7G,CAAC;AAED,SAAS,uBAAuB;IAC9B,IAAI,CAAC;QACH,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC;gBACjC,CAAC,IAAI,CAAC,UAAU,CAAC,qBAAqB,CAAC;gBACvC,CAAC,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC;gBAAE,SAAS;YAClD,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YACjC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,cAAc;gBAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;AAC/B,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,WAAW,CAAC,OAA0B;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAClD,IAAI,CAAC;QACH,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,0CAA0C;QAC3E,uBAAuB,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC,CAAC,wDAAwD;IACxE,CAAC;AACH,CAAC"}
+{"version":3,"file":"notice-marker.js","sourceRoot":"","sources":["../../src/lib/notice-marker.ts"],"names":[],"mappings":"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"}

package/dist/lib/outcomeObjectiveLines.d.ts

@@ -0,0 +1,34 @@
+/**
+ * TASK-817 (WP-818, TEN-4575): the lines `pb outcome show` and the MCP `context action=outcome` print
+ * for a key result's own objective and its sibling key results. The kernel read
+ * (convex/outcomes/readings.ts `showOutcome`) decides the objective and the siblings; this file
+ * only words them, once, for both surfaces (RULE-128, RULE-664).
+ *
+ * Pure, no I/O, zero imports: copied into each connector by scripts/generate-mcp-embedded-copies.mjs.
+ * Field sanitization is the caller's (each connector's own `sanitizeSingleLineField`), passed in
+ * as `clean`, the same split seatSentence.ts uses.
+ */
+export interface OutcomeObjectiveSibling {
+    entryId: string;
+    name: string;
+    currentValue: number | null;
+    targetValue: number | null;
+    /** Every loaded reading is superseded and more remain (the spine's own flag). The line prints the
+     *  state word either way: the kernel already counts the latest superseded reading (DEC-2488). */
+    readingUnresolved: boolean;
+    /** The key result's state word, from the kernel constant the server reads (DEC-2488, RULE-664);
+     *  absent from a server older than it. */
+    stateWord?: string;
+}
+export interface OutcomeObjectiveView {
+    objective: {
+        entryId: string;
+        name: string;
+        siblings: OutcomeObjectiveSibling[];
+        hiddenSiblings: number;
+        truncated: boolean;
+    } | null;
+    objectiveLookup: 'found' | 'none' | 'capped' | 'unavailable';
+}
+export declare function formatOutcomeObjectiveLines(view: OutcomeObjectiveView, clean: (value: string) => string): string[];
+//# sourceMappingURL=outcomeObjectiveLines.d.ts.map

package/dist/lib/outcomeObjectiveLines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcomeObjectiveLines.d.ts","sourceRoot":"","sources":["../../src/lib/outcomeObjectiveLines.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;qGACiG;IACjG,iBAAiB,EAAE,OAAO,CAAC;IAC3B;8CAC0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACpC,SAAS,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,uBAAuB,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACrI,eAAe,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAC;CAC7D;AAgBD,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,EAAE,CAUlH"}

package/dist/lib/outcomeObjectiveLines.js

@@ -0,0 +1,30 @@
+// GENERATED by scripts/generate-mcp-embedded-copies.mjs from kernel/outcomes/objectiveLines.ts.
+// DO NOT EDIT. Run `npm run mcp:embedded-copies` to regenerate.
+// Local runtime copy for the isolated connector build.
+const LOOKUP_LINE = {
+    none: 'none: no accepted objective holds this entry',
+    capped: 'not found: the objectives or key results read were capped before reaching this one',
+    unavailable: 'could not be read just now; run show again',
+};
+const INDENT = '              ';
+function siblingLine(kr, clean) {
+    const parts = [...(kr.stateWord ? [clean(kr.stateWord)] : []), ...(kr.currentValue === null ? [] : [`current ${kr.currentValue}`])];
+    if (kr.targetValue !== null)
+        parts.push(`target ${kr.targetValue}`);
+    return `${clean(kr.entryId)} — ${clean(kr.name)}${parts.length ? ` (${parts.join(', ')})` : ''}`;
+}
+export function formatOutcomeObjectiveLines(view, clean) {
+    const o = view.objective;
+    if (view.objectiveLookup !== 'found' || !o)
+        return [`  objective   ${LOOKUP_LINE[view.objectiveLookup === 'found' ? 'none' : view.objectiveLookup]}`];
+    const lines = [`  objective   ${clean(o.entryId)} — ${clean(o.name)}`];
+    if (o.siblings.length === 0 && !o.truncated)
+        return [...lines, '  siblings    none: the only key result under this objective'];
+    o.siblings.forEach((kr, i) => lines.push(`${i === 0 ? '  siblings    ' : INDENT}${siblingLine(kr, clean)}`));
+    // truncated with no counted sibling hidden: the read was capped workspace-wide, so more may exist.
+    const more = o.hiddenSiblings > 0 ? `and at least ${o.hiddenSiblings} more not shown` : 'more may exist: the key results read were capped';
+    if (o.truncated)
+        lines.push(`${o.siblings.length === 0 ? '  siblings    ' : INDENT}${more}`);
+    return lines;
+}
+//# sourceMappingURL=outcomeObjectiveLines.js.map

package/dist/lib/outcomeObjectiveLines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcomeObjectiveLines.js","sourceRoot":"","sources":["../../src/lib/outcomeObjectiveLines.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,gEAAgE;AAChE,uDAAuD;AA8BvD,MAAM,WAAW,GAA8E;IAC9F,IAAI,EAAE,8CAA8C;IACpD,MAAM,EAAE,oFAAoF;IAC5F,WAAW,EAAE,4CAA4C;CACzD,CAAC;AAEF,MAAM,MAAM,GAAG,gBAAgB,CAAC;AAEhC,SAAS,WAAW,CAAC,EAA2B,EAAE,KAAgC;IACjF,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC;IACpI,IAAI,EAAE,CAAC,WAAW,KAAK,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IACpE,OAAO,GAAG,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAClG,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,IAA0B,EAAE,KAAgC;IACvG,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;IACzB,IAAI,IAAI,CAAC,eAAe,KAAK,OAAO,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,iBAAiB,WAAW,CAAC,IAAI,CAAC,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;IACtJ,MAAM,KAAK,GAAG,CAAC,iBAAiB,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvE,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QAAE,OAAO,CAAC,GAAG,KAAK,EAAE,8DAA8D,CAAC,CAAC;IAC/H,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7G,mGAAmG;IACnG,MAAM,IAAI,GAAG,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,cAAc,iBAAiB,CAAC,CAAC,CAAC,kDAAkD,CAAC;IAC3I,IAAI,CAAC,CAAC,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC,CAAC;IAC7F,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/lib/ownerLine.d.ts

@@ -0,0 +1,90 @@
+/**
+ * WP-753 O5b fix round 1 (item 2): the ONE judged core for "how do we say who owns this
+ * entry" — the CLI (packages/cli/src/formatters/entry.ts), MCP
+ * (packages/mcp-server/src/tools/knowledge-helpers.ts), and the browser Rail
+ * (EntryRailPreview.svelte) each held a hand-copied switch over the same states; the
+ * Svelte copy alone drifted with a silent `default:` arm that would print "Owner: unresolved"
+ * for an unhandled kind instead of failing to compile. Pure, no I/O — kernel never imports
+ * convex, so this is a structural five-kind union that convex's `EntryOwnerRead`
+ * (convex/governance/entryOwnershipRead.ts) satisfies exactly, not a copy of it.
+ *
+ * DEC-1793 (RULE-632) deleted the `default`, `overflow` and `unavailable` kinds this union used
+ * to carry: a working record with no ownership row now reads as the plain `none` kind below —
+ * no synthetic Team Lead, no overflow guess.
+ *
+ * DEC-1944 (TASK-614; WP-783): a role or a team is an organisation definition with no
+ * owner of its own; its line says where it lives instead (`placed`). DEC-2064 (TASK-860): the word
+ * is `PLACED_WORD` on every surface, CLI, MCP and the Rail alike (RULE-664). DEC-1950 (TASK-768):
+ * a role's Rail header puts that word before the pill, a team's parent pill stands alone and its
+ * hover reads the path from the organisation down (`placedRailWord`, `placedRailHover`).
+ *
+ * Surface-specific bits are NOT here, by design — the caller applies them: per-field name
+ * sanitization (CLI/MCP's `sanitizeSingleLineField`), the bold label (MCP), and
+ * whether raw ids are shown at all (browser Rail: never — Rail-Design-Thesis.md:278 forbids
+ * Convex `_id`s as Noise; CLI/MCP: yes, a terminal user pastes them into a repair command).
+ */
+export type OwnerLine = {
+    kind: 'one';
+    team: {
+        name: string;
+    };
+    role: {
+        name: string;
+    };
+} | {
+    kind: 'none';
+} | {
+    kind: 'many';
+    count: number;
+    truncated: boolean;
+} | {
+    kind: 'dangling';
+    teamId: string;
+    roleId: string;
+    team?: {
+        name: string;
+    };
+    role?: {
+        name: string;
+    };
+} | {
+    kind: 'placed';
+    of: 'role' | 'team';
+    team: {
+        name: string;
+    };
+    ancestors: string[];
+    ancestorsTruncated: boolean;
+};
+/** DEC-2064 (TASK-860; RULE-664): the one word before the team an entry lives in, on every surface.
+ *  CLI and MCP print it for a role and a team alike; the Rail prints it only before a role's team
+ *  pill, because on a team's header it would read as if the team were its own team (DEC-1950). */
+export declare const PLACED_WORD = "Team:";
+export interface FormatOwnerLineOptions {
+    /** CLI/MCP keep the raw id for repair commands (default true). The browser Rail passes
+     *  `false` — Convex ids are Noise there, never Signal. */
+    ids?: boolean;
+    /** MCP bolds the leading label (`**Owner:**`, `**Team:**`); CLI and the browser keep it plain (default false). */
+    bold?: boolean;
+}
+/** The owning role and its team as two names, for a surface that shows them apart (the browser
+ *  Rail's role pill with the team beside it, DEC-1932). `null` for every kind but `one`: those keep
+ *  their sentence from `formatOwnerLine`, which builds its `one` sentence from these same names. */
+export declare function ownerLineParts(owner: OwnerLine): {
+    role: string;
+    team: string;
+} | null;
+/** DEC-1950 (TASK-768): the word the Rail prints before the placed pill — `PLACED_WORD` for a
+ *  role's home team, `null` for a team's parent (the pill stands alone) and for every other kind. */
+export declare function placedRailWord(owner: OwnerLine): string | null;
+/** DEC-1950 (TASK-768): the Rail's hover text on the placed line and pill. A team: the path from the
+ *  organisation down to its parent, root first, led by `… › ` when the reader's walk was cut. A role:
+ *  the CLI/MCP sentence without ids. `null` for every other kind. */
+export declare function placedRailHover(owner: OwnerLine): string | null;
+/** Exhaustive over the five kinds above. The `default:` arm below is not a silent catch-all —
+ *  it assigns the narrowed remainder to a `never`-typed const, so an unhandled kind fails to
+ *  compile HERE regardless of which tsconfig's strictness flags apply at the call site
+ *  (kernel's own tsconfig is red pre-existing, unrelated to this PR, so exhaustiveness cannot
+ *  be left to ride on `noImplicitReturns` alone; WP-753 O5b fix round 3, addendum a). */
+export declare function formatOwnerLine(owner: OwnerLine, options?: FormatOwnerLineOptions): string;
+//# sourceMappingURL=ownerLine.d.ts.map

package/dist/lib/ownerLine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownerLine.d.ts","sourceRoot":"","sources":["../../src/lib/ownerLine.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,SAAS,GAClB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAE/D;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GAKnD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAMtG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,kBAAkB,EAAE,OAAO,CAAA;CAAE,CAAC;AAErH;;kGAEkG;AAClG,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,MAAM,WAAW,sBAAsB;IACtC;8DAC0D;IAC1D,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,kHAAkH;IAClH,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;oGAEoG;AACpG,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAEtF;AAED;qGACqG;AACrG,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAE9D;AAED;;qEAEqE;AACrE,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAK/D;AAED;;;;yFAIyF;AACzF,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAyC9F"}

package/dist/lib/ownerLine.js

@@ -0,0 +1,77 @@
+// GENERATED by scripts/generate-mcp-embedded-copies.mjs from kernel/organisationalAuthority/ownerLine.ts.
+// DO NOT EDIT. Run `npm run mcp:embedded-copies` to regenerate.
+// Local runtime copy for the isolated connector build.
+/** DEC-2064 (TASK-860; RULE-664): the one word before the team an entry lives in, on every surface.
+ *  CLI and MCP print it for a role and a team alike; the Rail prints it only before a role's team
+ *  pill, because on a team's header it would read as if the team were its own team (DEC-1950). */
+export const PLACED_WORD = 'Team:';
+/** The owning role and its team as two names, for a surface that shows them apart (the browser
+ *  Rail's role pill with the team beside it, DEC-1932). `null` for every kind but `one`: those keep
+ *  their sentence from `formatOwnerLine`, which builds its `one` sentence from these same names. */
+export function ownerLineParts(owner) {
+    return owner.kind === 'one' ? { role: owner.role.name, team: owner.team.name } : null;
+}
+/** DEC-1950 (TASK-768): the word the Rail prints before the placed pill — `PLACED_WORD` for a
+ *  role's home team, `null` for a team's parent (the pill stands alone) and for every other kind. */
+export function placedRailWord(owner) {
+    return owner.kind === 'placed' && owner.of === 'role' ? PLACED_WORD : null;
+}
+/** DEC-1950 (TASK-768): the Rail's hover text on the placed line and pill. A team: the path from the
+ *  organisation down to its parent, root first, led by `… › ` when the reader's walk was cut. A role:
+ *  the CLI/MCP sentence without ids. `null` for every other kind. */
+export function placedRailHover(owner) {
+    if (owner.kind !== 'placed')
+        return null;
+    if (owner.of === 'role')
+        return formatOwnerLine(owner, { ids: false });
+    const path = [...owner.ancestors, owner.team.name].join(' › ');
+    return owner.ancestorsTruncated ? `… › ${path}` : path;
+}
+/** Exhaustive over the five kinds above. The `default:` arm below is not a silent catch-all —
+ *  it assigns the narrowed remainder to a `never`-typed const, so an unhandled kind fails to
+ *  compile HERE regardless of which tsconfig's strictness flags apply at the call site
+ *  (kernel's own tsconfig is red pre-existing, unrelated to this PR, so exhaustiveness cannot
+ *  be left to ride on `noImplicitReturns` alone; WP-753 O5b fix round 3, addendum a). */
+export function formatOwnerLine(owner, options = {}) {
+    const ids = options.ids ?? true;
+    const word = owner.kind === 'placed' ? PLACED_WORD : 'Owner:';
+    const label = options.bold ? `**${word}**` : word;
+    switch (owner.kind) {
+        case 'one': {
+            const { role, team } = ownerLineParts(owner);
+            return `${label} ${role} in ${team}`;
+        }
+        case 'none': return `${label} none`;
+        case 'placed': return `${label} ${owner.team.name}`;
+        case 'many': return `${label} conflicting — ${owner.count}${owner.truncated ? '+' : ''} owners recorded`;
+        case 'dangling': {
+            // WP-753 O5b fix round 3, addendum b: lead with whichever name(s) survived —
+            // requiring BOTH team and role names dropped a fetched role name whenever only
+            // the team was gone (or vice versa), silently downgrading to the generic sentence.
+            const named = owner.team && owner.role
+                ? `${owner.role.name} in ${owner.team.name} is archived`
+                : owner.role
+                    ? `role ${owner.role.name} is archived`
+                    : owner.team
+                        ? `team ${owner.team.name} is archived`
+                        : 'the owning team or role is archived';
+            // WP-753 O5b fix round 4 (item 4): one voice for the unresolved state —
+            // "couldn't be resolved", not the earlier "unresolved".
+            return ids ? `${label} couldn't be resolved — ${named} (team ${owner.teamId}, role ${owner.roleId})` : `${label} couldn't be resolved — ${named}`;
+        }
+        default: {
+            // RULE-268 (round 1 review, PR #1180): fail LOUD, never silently render an unhandled
+            // kind's raw object through stripControlChars (which crashed an older globally-
+            // installed CLI live on the preview: `str.replace is not a function`, since the old
+            // `default:` arm returned the non-string `owner` value itself instead of a message).
+            // RULE-632/DEC-1742/copilot-instructions.md code rules refuse a wire-compat shim for a shape the write path
+            // no longer produces — an older client hitting a newer server's kind it has never seen
+            // throws with an explicit upgrade instruction instead. The `never` assignment below
+            // still buys compile-time exhaustiveness (a future kind added to `OwnerLine` without a
+            // case here fails to compile HERE, unrelated to this runtime guard).
+            const _exhaustive = owner;
+            throw new Error(`Unknown owner state "${String(owner.kind)}" — this client is older than the server; upgrade @productbrain/cli / @productbrain/mcp`);
+        }
+    }
+}
+//# sourceMappingURL=ownerLine.js.map

package/dist/lib/ownerLine.js.map

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

package/dist/lib/parseFields.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Parse --field key=value pairs into a data object.
+ * Splits on first `=` only to handle values containing `=`.
+ *
+ * Sweep finding #9: `-f`/`--field` is already REPEATABLE at the Commander layer
+ * (index.ts: `(val, prev) => [...prev, val]`) — that is this CLI's existing, documented
+ * convention for a multi-select/array field (e.g. a collection's `tags`,
+ * `type: 'multi-select'` server-side). But this function silently let the LAST occurrence of a
+ * repeated key clobber every earlier one (`data[key] = value` unconditionally), so
+ * `-f tags=a -f tags=b` sent only the string `"b"` — never
+ * an array, and silently dropping `a` besides. The server then rejects a bare string
+ * against an array-typed field ("rejects non-array input"). Fixed by accumulating repeated keys
+ * into an array instead of overwriting — a single-occurrence key (the overwhelming majority of
+ * calls, e.g. the documented `rationale="..."` example) is completely unaffected: no comma
+ * heuristics, no schema round-trip, no behavior change for free text that happens to contain a
+ * comma.
+ */
+export declare function parseFields(fields: string[]): Record<string, unknown>;
+//# sourceMappingURL=parseFields.d.ts.map

package/dist/lib/parseFields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseFields.d.ts","sourceRoot":"","sources":["../../src/lib/parseFields.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BrE"}

package/dist/lib/parseFields.js

@@ -0,0 +1,49 @@
+import { CLIError, ErrorCode } from './errors.js';
+/**
+ * Parse --field key=value pairs into a data object.
+ * Splits on first `=` only to handle values containing `=`.
+ *
+ * Sweep finding #9: `-f`/`--field` is already REPEATABLE at the Commander layer
+ * (index.ts: `(val, prev) => [...prev, val]`) — that is this CLI's existing, documented
+ * convention for a multi-select/array field (e.g. a collection's `tags`,
+ * `type: 'multi-select'` server-side). But this function silently let the LAST occurrence of a
+ * repeated key clobber every earlier one (`data[key] = value` unconditionally), so
+ * `-f tags=a -f tags=b` sent only the string `"b"` — never
+ * an array, and silently dropping `a` besides. The server then rejects a bare string
+ * against an array-typed field ("rejects non-array input"). Fixed by accumulating repeated keys
+ * into an array instead of overwriting — a single-occurrence key (the overwhelming majority of
+ * calls, e.g. the documented `rationale="..."` example) is completely unaffected: no comma
+ * heuristics, no schema round-trip, no behavior change for free text that happens to contain a
+ * comma.
+ */
+export function parseFields(fields) {
+    const data = {};
+    for (const field of fields) {
+        const eqIndex = field.indexOf('=');
+        if (eqIndex === -1) {
+            throw new CLIError(`Invalid --field format: "${field}". Expected key=value.`, {
+                code: ErrorCode.VALIDATION_FAILED,
+                category: 'validation',
+                guidance: 'Use --field key=value (split on first "=").',
+            });
+        }
+        const key = field.slice(0, eqIndex).trim();
+        const value = field.slice(eqIndex + 1).trim();
+        if (!key) {
+            throw new CLIError(`Invalid --field format: "${field}". Key cannot be empty.`, {
+                code: ErrorCode.VALIDATION_FAILED,
+                category: 'validation',
+                guidance: 'Provide a non-empty key before the "=" sign.',
+            });
+        }
+        if (Object.prototype.hasOwnProperty.call(data, key)) {
+            const existing = data[key];
+            data[key] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+        }
+        else {
+            data[key] = value;
+        }
+    }
+    return data;
+}
+//# sourceMappingURL=parseFields.js.map

package/dist/lib/parseFields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseFields.js","sourceRoot":"","sources":["../../src/lib/parseFields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CAAC,MAAgB;IAC3C,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,QAAQ,CAAC,4BAA4B,KAAK,wBAAwB,EAAE;gBAC7E,IAAI,EAAE,SAAS,CAAC,iBAAiB;gBACjC,QAAQ,EAAE,YAAY;gBACtB,QAAQ,EAAE,6CAA6C;aACvD,CAAC,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9C,IAAI,CAAC,GAAG,EAAE,CAAC;YACV,MAAM,IAAI,QAAQ,CAAC,4BAA4B,KAAK,yBAAyB,EAAE;gBAC9E,IAAI,EAAE,SAAS,CAAC,iBAAiB;gBACjC,QAAQ,EAAE,YAAY;gBACtB,QAAQ,EAAE,8CAA8C;aACxD,CAAC,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAkB,EAAE,KAAK,CAAC,CAAC;QAC1F,CAAC;aAAM,CAAC;YACP,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACF,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/lib/pinnedRole.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A folder's default acting role (DEC-1961, TASK-639, WP-809).
+ *
+ * `.productbrain/config.local.json` may carry `role` beside `profile`: the role id (ROL-N) this
+ * folder's sessions act as. `pb session start --role` wins over it. The role binds at session
+ * start (DEC-1715) and only labels attribution; a person key never carries it (DEC-1923), and a key bound to one role
+ * for an AI agent (DEC-2226) acts only as that role, so the kernel refuses any other pin. The kernel
+ * decides whether the person holds it (RULE-128): a role not held is refused, never swapped for
+ * another (RULE-632). A role id names a role in ONE workspace, so the pin's role is sent only when
+ * the pin's own profile supplies the key; under any other key it is not sent, and that is said.
+ *
+ * A refusal is thrown once and printed once, on stderr; the SessionStart hook pb installs runs
+ * `pb session start 2>&1`, so the agent reads it there (TASK-649, WP-810). Older installs and
+ * machine-level hooks may still discard stderr (TEN-3736). Only role refusals get
+ * this framing: any other failure is rethrown unchanged.
+ */
+import { CLIError } from './errors.js';
+/** The one test for a role refusal; session.ts's stale-preview-key recovery uses it too, so a role refusal is never relabelled. */
+export declare const isRoleRefusal: (err: unknown) => err is CLIError;
+/**
+ * Run a session start with `--role`, else the pin's role. A role refusal under `--role` gains the
+ * close-then-start fix (a role switch already names it); under the pin it names the pin and its fix. With no role asked for, `multi_role` gains
+ * the folder-pin way to name one, and `no_role` keeps the kernel's fix. Every other failure is
+ * rethrown unchanged.
+ */
+export declare function startWithPinnedRole<O extends {
+    role?: string;
+}>(options: O, json: boolean, start: (options: O) => Promise<void>): Promise<void>;
+//# sourceMappingURL=pinnedRole.d.ts.map

package/dist/lib/pinnedRole.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinnedRole.d.ts","sourceRoot":"","sources":["../../src/lib/pinnedRole.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,QAAQ,EAAkC,MAAM,aAAa,CAAC;AAqBvE,mIAAmI;AACnI,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,QAAkE,CAAC;AA2CvH;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACnE,OAAO,EAAE,CAAC,EACV,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC,CA4Bf"}