instar 1.3.236 → 1.3.238

package/dist/monitoring/GeminiLoopRunner.d.ts

@@ -0,0 +1,93 @@
+/**
+ * GeminiLoopRunner (need-gem-002, increment 2) — the budget-gated, dark-by-default
+ * service that makes the GeminiLoopDriver invocable.
+ *
+ * A multi-turn gemini loop can run for minutes (several turns × a turn each), so
+ * it CANNOT block an HTTP request. `startRun` admits a run (enabled? under
+ * concurrency cap? budget ok?), kicks off `driver.run()` in the background, and
+ * returns a `runId` immediately; the result lands in a bounded in-memory registry
+ * retrievable via `getRun`. Ships DARK (`enabled: false`); the `developmentAgent`
+ * gate turns it on for dev agents only.
+ *
+ * Subscription auth is structural: the runner's spawn dep is the production
+ * transport spawn (`buildGeminiChildEnv` strips every billing var), so no run can
+ * introduce an API key.
+ *
+ * Spec: docs/specs/gemini-multi-turn-loop-driver.md
+ */
+import { type GeminiLoopSpawn, type GeminiLoopHandleCapture, type GeminiLoopBudgetGate, type GeminiLoopResult } from './GeminiLoopDriver.js';
+export interface GeminiLoopDriverConfig {
+    enabled: boolean;
+    /** Model passed to every turn (explicit -m bypasses the router classifier). */
+    model: string;
+    /** Hard cap on turns per run. */
+    maxTurns: number;
+    /** Min ms between turns (anti-spin). */
+    minTurnIntervalMs: number;
+    /** Max concurrent runs. 1 keeps shared-cwd handle capture unambiguous. */
+    maxConcurrent: number;
+    /** Bounded registry size — oldest finished runs are evicted past this. */
+    maxRetainedRuns: number;
+    /** Sentinel the mentee emits when done. */
+    doneSentinel?: string;
+}
+export type GeminiLoopRunStatus = 'running' | 'done' | 'error';
+export interface GeminiLoopRunRecord {
+    runId: string;
+    status: GeminiLoopRunStatus;
+    goalPrompt: string;
+    model: string;
+    maxTurns: number;
+    startedAt: number;
+    finishedAt?: number;
+    result?: GeminiLoopResult;
+    error?: string;
+}
+export interface GeminiLoopStartRequest {
+    goalPrompt: string;
+    model?: string;
+    maxTurns?: number;
+}
+export type GeminiLoopStartOutcome = {
+    ok: true;
+    runId: string;
+} | {
+    ok: false;
+    reason: 'disabled' | 'at-capacity' | 'budget' | 'invalid';
+    detail?: string;
+};
+export interface GeminiLoopRunnerDeps {
+    config: GeminiLoopDriverConfig;
+    spawn: GeminiLoopSpawn;
+    captureHandle: GeminiLoopHandleCapture;
+    budgetGate: GeminiLoopBudgetGate;
+    now?: () => number;
+    genId?: () => string;
+    log?: (msg: string) => void;
+}
+export declare class GeminiLoopRunner {
+    private readonly config;
+    private readonly spawn;
+    private readonly captureHandle;
+    private readonly budgetGate;
+    private readonly now;
+    private readonly genId;
+    private readonly log;
+    private readonly runs;
+    private activeCount;
+    constructor(deps: GeminiLoopRunnerDeps);
+    isEnabled(): boolean;
+    activeRuns(): number;
+    /**
+     * Admit + launch a run. Returns immediately with a runId; the loop runs in the
+     * background. Admission order: feature enabled → under concurrency cap → valid
+     * goal → budget gate open.
+     */
+    startRun(req: GeminiLoopStartRequest): GeminiLoopStartOutcome;
+    getRun(runId: string): GeminiLoopRunRecord | null;
+    listRuns(): GeminiLoopRunRecord[];
+    private execute;
+    /** Keep the registry bounded — drop the oldest FINISHED runs past the cap. */
+    private evictOldFinished;
+}
+//# sourceMappingURL=GeminiLoopRunner.d.ts.map

package/dist/monitoring/GeminiLoopRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GeminiLoopRunner.d.ts","sourceRoot":"","sources":["../../src/monitoring/GeminiLoopRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAE/D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,mBAAmB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9F,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,KAAK,EAAE,eAAe,CAAC;IACvB,aAAa,EAAE,uBAAuB,CAAC;IACvC,UAAU,EAAE,oBAAoB,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;IAE5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0C;IAC/D,OAAO,CAAC,WAAW,CAAK;gBAEZ,IAAI,EAAE,oBAAoB;IAUtC,SAAS,IAAI,OAAO;IAIpB,UAAU,IAAI,MAAM;IAIpB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,sBAAsB,GAAG,sBAAsB;IAoC7D,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAIjD,QAAQ,IAAI,mBAAmB,EAAE;YAInB,OAAO;IA4BrB,8EAA8E;IAC9E,OAAO,CAAC,gBAAgB;CAYzB"}

package/dist/monitoring/GeminiLoopRunner.js

@@ -0,0 +1,134 @@
+/**
+ * GeminiLoopRunner (need-gem-002, increment 2) — the budget-gated, dark-by-default
+ * service that makes the GeminiLoopDriver invocable.
+ *
+ * A multi-turn gemini loop can run for minutes (several turns × a turn each), so
+ * it CANNOT block an HTTP request. `startRun` admits a run (enabled? under
+ * concurrency cap? budget ok?), kicks off `driver.run()` in the background, and
+ * returns a `runId` immediately; the result lands in a bounded in-memory registry
+ * retrievable via `getRun`. Ships DARK (`enabled: false`); the `developmentAgent`
+ * gate turns it on for dev agents only.
+ *
+ * Subscription auth is structural: the runner's spawn dep is the production
+ * transport spawn (`buildGeminiChildEnv` strips every billing var), so no run can
+ * introduce an API key.
+ *
+ * Spec: docs/specs/gemini-multi-turn-loop-driver.md
+ */
+import { randomUUID } from 'node:crypto';
+import { GeminiLoopDriver, } from './GeminiLoopDriver.js';
+export class GeminiLoopRunner {
+    config;
+    spawn;
+    captureHandle;
+    budgetGate;
+    now;
+    genId;
+    log;
+    runs = new Map();
+    activeCount = 0;
+    constructor(deps) {
+        this.config = deps.config;
+        this.spawn = deps.spawn;
+        this.captureHandle = deps.captureHandle;
+        this.budgetGate = deps.budgetGate;
+        this.now = deps.now ?? (() => Date.now());
+        this.genId = deps.genId ?? (() => randomUUID());
+        this.log = deps.log ?? (() => { });
+    }
+    isEnabled() {
+        return this.config.enabled === true;
+    }
+    activeRuns() {
+        return this.activeCount;
+    }
+    /**
+     * Admit + launch a run. Returns immediately with a runId; the loop runs in the
+     * background. Admission order: feature enabled → under concurrency cap → valid
+     * goal → budget gate open.
+     */
+    startRun(req) {
+        if (!this.isEnabled())
+            return { ok: false, reason: 'disabled' };
+        if (this.activeCount >= this.config.maxConcurrent) {
+            return { ok: false, reason: 'at-capacity', detail: `maxConcurrent=${this.config.maxConcurrent}` };
+        }
+        const goalPrompt = (req.goalPrompt ?? '').trim();
+        if (!goalPrompt)
+            return { ok: false, reason: 'invalid', detail: 'goalPrompt is required' };
+        const gate = this.budgetGate();
+        if (!gate.ok)
+            return { ok: false, reason: 'budget', detail: gate.reason };
+        const runId = this.genId();
+        const model = (req.model ?? this.config.model) || this.config.model;
+        const maxTurns = Number.isInteger(req.maxTurns) && req.maxTurns > 0
+            ? Math.min(req.maxTurns, this.config.maxTurns)
+            : this.config.maxTurns;
+        const record = {
+            runId,
+            status: 'running',
+            goalPrompt,
+            model,
+            maxTurns,
+            startedAt: this.now(),
+        };
+        this.runs.set(runId, record);
+        this.evictOldFinished();
+        this.activeCount += 1;
+        this.log(`[gemini-loop] run ${runId} started (model=${model}, maxTurns=${maxTurns})`);
+        // Fire-and-forget — do NOT await; the HTTP caller already has the runId.
+        void this.execute(record);
+        return { ok: true, runId };
+    }
+    getRun(runId) {
+        return this.runs.get(runId) ?? null;
+    }
+    listRuns() {
+        return [...this.runs.values()].sort((a, b) => b.startedAt - a.startedAt);
+    }
+    async execute(record) {
+        const driver = new GeminiLoopDriver({
+            spawn: this.spawn,
+            captureHandle: this.captureHandle,
+            budgetGate: this.budgetGate,
+        });
+        try {
+            const result = await driver.run({
+                model: record.model,
+                goalPrompt: record.goalPrompt,
+                maxTurns: record.maxTurns,
+                minTurnIntervalMs: this.config.minTurnIntervalMs,
+                doneSentinel: this.config.doneSentinel,
+            });
+            record.status = 'done';
+            record.result = result;
+            record.finishedAt = this.now();
+            this.log(`[gemini-loop] run ${record.runId} done (${result.stopReason}, ${result.turns.length} turns)`);
+        }
+        catch (err) {
+            record.status = 'error';
+            record.error = err instanceof Error ? err.message : String(err);
+            record.finishedAt = this.now();
+            this.log(`[gemini-loop] run ${record.runId} error: ${record.error}`);
+        }
+        finally {
+            this.activeCount = Math.max(0, this.activeCount - 1);
+        }
+    }
+    /** Keep the registry bounded — drop the oldest FINISHED runs past the cap. */
+    evictOldFinished() {
+        if (this.runs.size <= this.config.maxRetainedRuns)
+            return;
+        const finished = [...this.runs.values()]
+            .filter((r) => r.status !== 'running')
+            .sort((a, b) => (a.finishedAt ?? a.startedAt) - (b.finishedAt ?? b.startedAt));
+        let over = this.runs.size - this.config.maxRetainedRuns;
+        for (const r of finished) {
+            if (over <= 0)
+                break;
+            this.runs.delete(r.runId);
+            over -= 1;
+        }
+    }
+}
+//# sourceMappingURL=GeminiLoopRunner.js.map

package/dist/monitoring/GeminiLoopRunner.js.map

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

package/dist/monitoring/ParallelWorkOverlap.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ParallelWorkOverlap — the pure cross-topic overlap detector that the
+ * ParallelWorkSentinel (Phase B) runs on a cadence (docs/specs/parallel-activity-coherence.md).
+ *
+ * Convergence hardened this against false-positive nudges (a noisy councilor gets
+ * muted, which is worse than silence). The containment lives HERE, in pure logic:
+ *  - ACTIVITY GATE: only topics worked within a recent window are compared (a dormant
+ *    overlap is not a live duplication risk — mirrors BurnDetector's activity gate).
+ *  - SPECIFICITY: overlap rests on shared HIGH-SPECIFICITY tags (entities/files/identifiers,
+ *    already filtered of boilerplate by extractTags) and requires ≥ minSharedSpecific of
+ *    them — never on generic words. Rarer shared tags weigh more (IDF over the candidate set).
+ *  - SELF-EXCLUSION: a topic never matches itself.
+ *  - SIGNATURE: the sorted shared-tag SET — the dedup key the sentinel uses (with hysteresis)
+ *    so a slowly-evolving focus does not re-nag and a genuinely new overlap is not suppressed.
+ *
+ * This module is PURE (no I/O, no time except the injected nowMs) so it is exhaustively
+ * unit-testable. The stateful dedup/cooldown/cadence/nudge lives in the sentinel.
+ */
+/** The subset of a TopicActivity this detector needs (structurally compatible with ParallelActivityIndex output). */
+export interface OverlapCandidate {
+    topicId: number;
+    tags: string[];
+    updatedAt: number | null;
+    running?: boolean;
+}
+export interface OverlapPair {
+    /** Lower topicId first (stable pair key). */
+    topicA: number;
+    topicB: number;
+    /** The high-specificity tokens both topics share (the genuine overlap). */
+    sharedTags: string[];
+    /** IDF-weighted overlap strength over the candidate set; higher = rarer shared tokens. */
+    score: number;
+    /** Sorted sharedTags joined — the dedup signature (the sentinel keys cooldown on the PAIR, hysteresis on this). */
+    signature: string;
+}
+export interface DetectOverlapsOptions {
+    nowMs: number;
+    /** Only compare topics whose updatedAt is within this window (default 4h). Null updatedAt ⇒ excluded. */
+    activityWindowMs?: number;
+    /** Require at least this many shared high-specificity tags (default 1). */
+    minSharedSpecific?: number;
+    /** When true, at least ONE side of each pair must be currently running (default true — we nudge live work). */
+    requireRunning?: boolean;
+}
+/**
+ * Detect overlapping work across topics. Returns one OverlapPair per genuinely-overlapping
+ * pair, strongest first. Pure: same inputs → same output.
+ */
+export declare function detectOverlaps(candidates: OverlapCandidate[], opts: DetectOverlapsOptions): OverlapPair[];
+/** Stable pair key for sentinel-side cooldown (survives focus edits / signature drift). */
+export declare function pairKey(topicA: number, topicB: number): string;
+/**
+ * Hysteresis: should a NEW overlap signature for an already-nudged pair re-fire? Only when
+ * the shared-tag set has changed materially (Jaccard(old,new) < threshold) — so a one-token
+ * focus tweak does not re-nag, but a genuinely different overlap does.
+ */
+export declare function signatureChangedMaterially(oldSig: string, newSig: string, jaccardThreshold?: number): boolean;
+//# sourceMappingURL=ParallelWorkOverlap.d.ts.map

package/dist/monitoring/ParallelWorkOverlap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParallelWorkOverlap.d.ts","sourceRoot":"","sources":["../../src/monitoring/ParallelWorkOverlap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,qHAAqH;AACrH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,mHAAmH;IACnH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,yGAAyG;IACzG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+GAA+G;IAC/G,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,gBAAgB,EAAE,EAC9B,IAAI,EAAE,qBAAqB,GAC1B,WAAW,EAAE,CAqCf;AAED,2FAA2F;AAC3F,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,SAAM,GAAG,OAAO,CAU1G"}

package/dist/monitoring/ParallelWorkOverlap.js

@@ -0,0 +1,86 @@
+/**
+ * ParallelWorkOverlap — the pure cross-topic overlap detector that the
+ * ParallelWorkSentinel (Phase B) runs on a cadence (docs/specs/parallel-activity-coherence.md).
+ *
+ * Convergence hardened this against false-positive nudges (a noisy councilor gets
+ * muted, which is worse than silence). The containment lives HERE, in pure logic:
+ *  - ACTIVITY GATE: only topics worked within a recent window are compared (a dormant
+ *    overlap is not a live duplication risk — mirrors BurnDetector's activity gate).
+ *  - SPECIFICITY: overlap rests on shared HIGH-SPECIFICITY tags (entities/files/identifiers,
+ *    already filtered of boilerplate by extractTags) and requires ≥ minSharedSpecific of
+ *    them — never on generic words. Rarer shared tags weigh more (IDF over the candidate set).
+ *  - SELF-EXCLUSION: a topic never matches itself.
+ *  - SIGNATURE: the sorted shared-tag SET — the dedup key the sentinel uses (with hysteresis)
+ *    so a slowly-evolving focus does not re-nag and a genuinely new overlap is not suppressed.
+ *
+ * This module is PURE (no I/O, no time except the injected nowMs) so it is exhaustively
+ * unit-testable. The stateful dedup/cooldown/cadence/nudge lives in the sentinel.
+ */
+const DEFAULT_WINDOW_MS = 4 * 60 * 60 * 1000; // 4h
+/**
+ * Detect overlapping work across topics. Returns one OverlapPair per genuinely-overlapping
+ * pair, strongest first. Pure: same inputs → same output.
+ */
+export function detectOverlaps(candidates, opts) {
+    const windowMs = opts.activityWindowMs ?? DEFAULT_WINDOW_MS;
+    const minShared = opts.minSharedSpecific ?? 1;
+    const requireRunning = opts.requireRunning ?? true;
+    const cutoff = opts.nowMs - windowMs;
+    // Activity gate: only recently-worked topics with at least one specific tag.
+    const active = candidates.filter((c) => c.updatedAt !== null && c.updatedAt >= cutoff && c.tags.length > 0);
+    // IDF: a tag shared by FEW topics is more meaningful than one shared by many.
+    const docFreq = new Map();
+    for (const c of active)
+        for (const t of new Set(c.tags))
+            docFreq.set(t, (docFreq.get(t) ?? 0) + 1);
+    const idf = (tag) => {
+        const df = docFreq.get(tag) ?? 1;
+        return Math.log(1 + active.length / df); // rarer ⇒ higher
+    };
+    const pairs = [];
+    for (let i = 0; i < active.length; i++) {
+        for (let j = i + 1; j < active.length; j++) {
+            const a = active[i];
+            const b = active[j];
+            if (a.topicId === b.topicId)
+                continue; // self-exclusion (defensive)
+            if (requireRunning && !a.running && !b.running)
+                continue;
+            const bTags = new Set(b.tags);
+            const shared = [...new Set(a.tags)].filter((t) => bTags.has(t));
+            if (shared.length < minShared)
+                continue;
+            const score = shared.reduce((s, t) => s + idf(t), 0);
+            const sorted = [...shared].sort();
+            const [topicA, topicB] = a.topicId < b.topicId ? [a.topicId, b.topicId] : [b.topicId, a.topicId];
+            pairs.push({ topicA, topicB, sharedTags: sorted, score, signature: sorted.join('|') });
+        }
+    }
+    pairs.sort((x, y) => y.score - x.score);
+    return pairs;
+}
+/** Stable pair key for sentinel-side cooldown (survives focus edits / signature drift). */
+export function pairKey(topicA, topicB) {
+    return topicA < topicB ? `${topicA}:${topicB}` : `${topicB}:${topicA}`;
+}
+/**
+ * Hysteresis: should a NEW overlap signature for an already-nudged pair re-fire? Only when
+ * the shared-tag set has changed materially (Jaccard(old,new) < threshold) — so a one-token
+ * focus tweak does not re-nag, but a genuinely different overlap does.
+ */
+export function signatureChangedMaterially(oldSig, newSig, jaccardThreshold = 0.6) {
+    if (oldSig === newSig)
+        return false;
+    const a = new Set(oldSig ? oldSig.split('|') : []);
+    const b = new Set(newSig ? newSig.split('|') : []);
+    if (a.size === 0 && b.size === 0)
+        return false;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    const union = a.size + b.size - inter;
+    const jaccard = union === 0 ? 1 : inter / union;
+    return jaccard < jaccardThreshold;
+}
+//# sourceMappingURL=ParallelWorkOverlap.js.map

package/dist/monitoring/ParallelWorkOverlap.js.map

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

package/dist/monitoring/ParallelWorkSentinel.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ParallelWorkSentinel — the proactive overlap councilor (Parallel-Work Awareness
+ * Phase B; docs/specs/parallel-activity-coherence.md, Part 2).
+ *
+ * On a cadence it reads the cross-topic activity index, runs the pure overlap detector,
+ * and — for genuinely-fresh overlaps — emits ONE 'overlap' nudge so the agent learns its
+ * other hand is already on the same work (the willpower-trap fix: the signal comes TO the
+ * agent, it doesn't rely on the agent remembering to query). SIGNAL-ONLY — it never gates,
+ * blocks, or mutates anything.
+ *
+ * Convergence-mandated containment (a noisy councilor gets muted, which is worse than
+ * silence), all enforced here statefully on top of the pure detector's containment:
+ *  - PAIR-KEYED COOLDOWN: at most one nudge per (topicA,topicB) per `nudgeCooldownMs`
+ *    (default 60min) — survives focus edits, so responding to a nudge can't re-trigger it.
+ *  - SIGNATURE HYSTERESIS: within the cooldown, a re-nudge only fires if the shared-tag SET
+ *    changed materially (a genuinely new overlap), not on a one-token focus tweak.
+ *  - It is the LEASE-HOLDER's job to run this (the caller gates ticks on holdsLease) so the
+ *    same overlap isn't nudged twice from two machines.
+ *
+ * Ships DARK (the route/config default is enabled:false) — graduate after it's proven quiet.
+ */
+import { EventEmitter } from 'node:events';
+import { type OverlapCandidate, type OverlapPair } from './ParallelWorkOverlap.js';
+export interface ParallelWorkSentinelOptions {
+    /** Pull the current cross-topic activities (e.g. ParallelActivityIndex.activities()). */
+    getActivities: (nowMs: number) => OverlapCandidate[];
+    /** Min ms between nudges for the same topic pair (default 60min). */
+    nudgeCooldownMs?: number;
+    /** Only compare topics worked within this window (passed to the detector; default 4h). */
+    activityWindowMs?: number;
+    /** Require ≥ this many shared high-specificity tags (default 1). */
+    minSharedSpecific?: number;
+    /** Audit sink for every transition (detected/nudged/deduped) — default-on housekeeping. */
+    audit?: (event: ParallelWorkAuditEvent) => void;
+}
+export interface ParallelWorkAuditEvent {
+    kind: 'nudged' | 'deduped-cooldown' | 'deduped-hysteresis';
+    pair: OverlapPair;
+    atMs: number;
+}
+/** Emitted to the agent when a fresh overlap is found. The one user-facing signal. */
+export interface OverlapNudge {
+    pair: OverlapPair;
+    atMs: number;
+    message: string;
+}
+export interface ParallelWorkSentinelEvents {
+    overlap: [nudge: OverlapNudge];
+}
+export declare class ParallelWorkSentinel extends EventEmitter {
+    private readonly opts;
+    private readonly state;
+    constructor(opts: ParallelWorkSentinelOptions);
+    /** Run one cadence tick. Pure-ish: side effects are the emitted nudges + the audit sink. */
+    tick(nowMs: number): OverlapNudge[];
+    /** Test/inspection helper: how many pairs are being tracked for dedup. */
+    trackedPairCount(): number;
+}
+//# sourceMappingURL=ParallelWorkSentinel.d.ts.map

package/dist/monitoring/ParallelWorkSentinel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParallelWorkSentinel.d.ts","sourceRoot":"","sources":["../../src/monitoring/ParallelWorkSentinel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,2BAA2B;IAC1C,yFAAyF;IACzF,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,gBAAgB,EAAE,CAAC;IACrD,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2FAA2F;IAC3F,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,QAAQ,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;IAC3D,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAOD,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;CAChC;AAED,qBAAa,oBAAqB,SAAQ,YAAY;IAGxC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAEzB,IAAI,EAAE,2BAA2B;IAI9D,4FAA4F;IAC5F,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE;IA6CnC,0EAA0E;IAC1E,gBAAgB,IAAI,MAAM;CAG3B"}

package/dist/monitoring/ParallelWorkSentinel.js

@@ -0,0 +1,79 @@
+/**
+ * ParallelWorkSentinel — the proactive overlap councilor (Parallel-Work Awareness
+ * Phase B; docs/specs/parallel-activity-coherence.md, Part 2).
+ *
+ * On a cadence it reads the cross-topic activity index, runs the pure overlap detector,
+ * and — for genuinely-fresh overlaps — emits ONE 'overlap' nudge so the agent learns its
+ * other hand is already on the same work (the willpower-trap fix: the signal comes TO the
+ * agent, it doesn't rely on the agent remembering to query). SIGNAL-ONLY — it never gates,
+ * blocks, or mutates anything.
+ *
+ * Convergence-mandated containment (a noisy councilor gets muted, which is worse than
+ * silence), all enforced here statefully on top of the pure detector's containment:
+ *  - PAIR-KEYED COOLDOWN: at most one nudge per (topicA,topicB) per `nudgeCooldownMs`
+ *    (default 60min) — survives focus edits, so responding to a nudge can't re-trigger it.
+ *  - SIGNATURE HYSTERESIS: within the cooldown, a re-nudge only fires if the shared-tag SET
+ *    changed materially (a genuinely new overlap), not on a one-token focus tweak.
+ *  - It is the LEASE-HOLDER's job to run this (the caller gates ticks on holdsLease) so the
+ *    same overlap isn't nudged twice from two machines.
+ *
+ * Ships DARK (the route/config default is enabled:false) — graduate after it's proven quiet.
+ */
+import { EventEmitter } from 'node:events';
+import { detectOverlaps, pairKey, signatureChangedMaterially, } from './ParallelWorkOverlap.js';
+export class ParallelWorkSentinel extends EventEmitter {
+    opts;
+    state = new Map();
+    constructor(opts) {
+        super();
+        this.opts = opts;
+    }
+    /** Run one cadence tick. Pure-ish: side effects are the emitted nudges + the audit sink. */
+    tick(nowMs) {
+        const activities = this.opts.getActivities(nowMs);
+        const pairs = detectOverlaps(activities, {
+            nowMs,
+            activityWindowMs: this.opts.activityWindowMs,
+            minSharedSpecific: this.opts.minSharedSpecific,
+            requireRunning: true,
+        });
+        const cooldown = this.opts.nudgeCooldownMs ?? 60 * 60 * 1000;
+        const fired = [];
+        for (const pair of pairs) {
+            const key = pairKey(pair.topicA, pair.topicB);
+            const prev = this.state.get(key);
+            if (prev) {
+                const withinCooldown = nowMs - prev.lastNudgedMs < cooldown;
+                if (withinCooldown && !signatureChangedMaterially(prev.lastSignature, pair.signature)) {
+                    this.opts.audit?.({ kind: 'deduped-hysteresis', pair, atMs: nowMs });
+                    // refresh the stored signature (track drift) but do NOT re-nudge
+                    this.state.set(key, { lastSignature: pair.signature, lastNudgedMs: prev.lastNudgedMs });
+                    continue;
+                }
+                if (withinCooldown && signatureChangedMaterially(prev.lastSignature, pair.signature)) {
+                    // Material change but still inside the cooldown window: suppress, record drift.
+                    this.opts.audit?.({ kind: 'deduped-cooldown', pair, atMs: nowMs });
+                    this.state.set(key, { lastSignature: pair.signature, lastNudgedMs: prev.lastNudgedMs });
+                    continue;
+                }
+            }
+            // Fresh (never nudged, or past cooldown) → nudge.
+            this.state.set(key, { lastSignature: pair.signature, lastNudgedMs: nowMs });
+            const nudge = {
+                pair,
+                atMs: nowMs,
+                message: `Heads up: topics ${pair.topicA} and ${pair.topicB} look like overlapping work ` +
+                    `(shared: ${pair.sharedTags.join(', ')}). You may be duplicating — worth aligning before you go further.`,
+            };
+            this.opts.audit?.({ kind: 'nudged', pair, atMs: nowMs });
+            this.emit('overlap', nudge);
+            fired.push(nudge);
+        }
+        return fired;
+    }
+    /** Test/inspection helper: how many pairs are being tracked for dedup. */
+    trackedPairCount() {
+        return this.state.size;
+    }
+}
+//# sourceMappingURL=ParallelWorkSentinel.js.map

package/dist/monitoring/ParallelWorkSentinel.js.map

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

package/dist/monitoring/geminiLoopProduction.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Production wiring for the GeminiLoopDriver (need-gem-002, increment 2).
+ *
+ * Turns the injected-dependency engine (`GeminiLoopDriver`) into real
+ * subscription-auth gemini spawns:
+ *   - `createGeminiLoopSpawn`     — routes every turn through the gemini transport
+ *                                   (`spawnGeminiAndWait` + `buildGeminiChildEnv`,
+ *                                   which strips every billing env var → subscription
+ *                                   OAuth is the only possible auth path).
+ *   - `parseLatestGeminiSessionHandle` — pure parser of `gemini --list-sessions`
+ *                                   output → the FRESHEST session's UUID (the one
+ *                                   turn 1 just created). Min-age, not list order.
+ *   - `createGeminiHandleCapture` — runs `--list-sessions` via the transport and
+ *                                   parses it; returns null if no handle resolves
+ *                                   (the engine then ABORTS rather than guessing).
+ *   - `createQuotaBudgetGate`     — wraps the existing QuotaTracker so a loop refuses
+ *                                   to start / continue under load or spend pressure.
+ *
+ * Spec: docs/specs/gemini-multi-turn-loop-driver.md
+ */
+import type { GeminiLoopSpawn, GeminiLoopHandleCapture, GeminiLoopBudgetGate } from './GeminiLoopDriver.js';
+/** Default per-turn spawn timeout (a single gemini turn). */
+export declare const DEFAULT_GEMINI_TURN_TIMEOUT_MS = 180000;
+/**
+ * Parse `gemini --list-sessions` stdout and return the FRESHEST session's UUID.
+ *
+ * Each session row looks like:
+ *   `  3. Remember the codeword... (Just now) [ef951c6e-49b4-49df-a8f0-b8aa62b4403f]`
+ * The age is the parenthesised group immediately before the `[uuid]` bracket
+ * (anchored there so parentheses inside the title don't interfere). We pick the
+ * MINIMUM age rather than trusting list order, so the handle is the session turn 1
+ * just created. Returns null when no row parses.
+ */
+export declare function parseLatestGeminiSessionHandle(stdout: string): string | null;
+/**
+ * Production gemini spawn — every turn routes through the subscription-auth
+ * transport. `buildGeminiChildEnv()` strips all billing env vars, so no argv this
+ * receives can introduce an API key.
+ */
+export declare function createGeminiLoopSpawn(geminiPath: string, turnTimeoutMs?: number): GeminiLoopSpawn;
+/**
+ * Production handle capture — after turn 1, list sessions and pick the freshest.
+ * Single-concurrency (`maxConcurrent: 1`) keeps this unambiguous: turn 1 just ran,
+ * so its session is the "Just now" / min-age row even if other gemini one-shots
+ * (e.g. cross-model review) created older sessions in the shared cwd.
+ */
+export declare function createGeminiHandleCapture(geminiPath: string, listTimeoutMs?: number): GeminiLoopHandleCapture;
+/** Minimal slice of QuotaTracker the budget gate needs. */
+export interface SpawnAdmissionSource {
+    shouldSpawnSession(): {
+        allowed: boolean;
+        reason: string;
+    };
+}
+/**
+ * Production budget gate — reuses the existing QuotaTracker spawn-admission
+ * decision (the same daily-spend / load-shedding signal every other instar spawn
+ * respects). Fails OPEN if no tracker is wired (the engine's own maxTurns +
+ * spawn-failure handling still bound the loop).
+ */
+export declare function createQuotaBudgetGate(quota: SpawnAdmissionSource | null | undefined): GeminiLoopBudgetGate;
+//# sourceMappingURL=geminiLoopProduction.d.ts.map

package/dist/monitoring/geminiLoopProduction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geminiLoopProduction.d.ts","sourceRoot":"","sources":["../../src/monitoring/geminiLoopProduction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EACV,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAE/B,6DAA6D;AAC7D,eAAO,MAAM,8BAA8B,SAAU,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY5E;AAkBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,aAAa,GAAE,MAAuC,GACrD,eAAe,CAQjB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,aAAa,GAAE,MAAe,GAC7B,uBAAuB,CAiBzB;AAED,2DAA2D;AAC3D,MAAM,WAAW,oBAAoB;IACnC,kBAAkB,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,GAC7C,oBAAoB,CAMtB"}