instar 1.3.269 → 1.3.270

package/dist/coordination/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Coordination Mandate — shared types.
+ *
+ * A Coordination Mandate is a human-authored, signed, bounded, conditioned,
+ * revocable, audited delegation of SPECIFIC authorities to a SPECIFIC pair of
+ * agents for a SPECIFIC purpose and bounded time. It moves the human's
+ * authorization from per-action to standing-policy WITHOUT removing the human as
+ * the authorizer — preserving `requester ≠ authorizer` (the agent is the
+ * requester; the human-authored mandate is the authorizer).
+ *
+ * Spec: docs/specs/coordination-mandate.md (§4 concrete shape). The first mandate's
+ * resolved bounds (Justin's A/A/B sign-off, 2026-06-05): cutover stays his manual
+ * click; issuance is dashboard-PIN-gated; the first mandate carries only authorities
+ * 1–2 (exchange-read-credential + sign-code-review), NOT execute-cutover.
+ */
+/** A single delegated authority within a mandate. */
+export interface Authority {
+    /** The action this authority permits, e.g. 'exchange-read-credential' | 'sign-code-review' | 'execute-cutover'. */
+    action: string;
+    /** Explicit bounds the action's params must satisfy (exact-match per key). */
+    bounds: Record<string, unknown>;
+    /** Optional objective gate that must evaluate true before the action is allowed,
+     *  e.g. 'integrity-gate-pass' | 'parity-zero-divergence'. Resolved from REAL state,
+     *  never from an agent's assertion. */
+    requiresCondition?: string;
+}
+/** The human-authored delegation. `authProof` covers all other fields. */
+export interface CoordinationMandate {
+    id: string;
+    /** e.g. 'feedback-migration'. */
+    scope: string;
+    /** The two agents bound by the mandate, by routing fingerprint. */
+    agents: [string, string];
+    authorities: Authority[];
+    /** Always the human author identifier (e.g. 'justin'). */
+    author: string;
+    createdAt: string;
+    expiresAt: string;
+    /** Set when revoked; checked on every action. */
+    revoked: {
+        at: string;
+        reason: string;
+    } | null;
+    /** Authorship proof — an HMAC over the canonical (proof-excluded) mandate bytes,
+     *  produced ONLY by the PIN-gated issuance path. An agent cannot mint or widen its
+     *  own mandate without it; a forged/edited mandate fails verification. */
+    authProof: string;
+}
+export type MandateDecision = 'allow' | 'deny';
+/** The input to a gate evaluation — what the agent is asking to do. */
+export interface MandateEvaluation {
+    action: string;
+    params: Record<string, unknown>;
+    /** The calling agent's routing fingerprint (must be a named party). */
+    agentFp: string;
+    mandateId: string;
+}
+/** A single audited gate decision (one row of the hash-chained audit). */
+export interface MandateAuditEntry {
+    ts: string;
+    mandateId: string;
+    agentFp: string;
+    action: string;
+    decision: MandateDecision;
+    /** Human-readable reason — which check passed/failed. */
+    reason: string;
+    /** The condition result when a `requiresCondition` was evaluated (else null). */
+    conditionResult: boolean | null;
+    /** Hash of the previous entry (genesis = ''), making the log tamper-evident (T8). */
+    prevHash: string;
+    /** sha256(prevHash + canonical(this-entry-without-hash)). */
+    hash: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/coordination/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/coordination/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACxB,mHAAmH;IACnH,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC;;2CAEuC;IACvC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzB,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/C;;8EAE0E;IAC1E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/C,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,CAAC;IAC1B,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,eAAe,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/coordination/types.js

@@ -0,0 +1,17 @@
+/**
+ * Coordination Mandate — shared types.
+ *
+ * A Coordination Mandate is a human-authored, signed, bounded, conditioned,
+ * revocable, audited delegation of SPECIFIC authorities to a SPECIFIC pair of
+ * agents for a SPECIFIC purpose and bounded time. It moves the human's
+ * authorization from per-action to standing-policy WITHOUT removing the human as
+ * the authorizer — preserving `requester ≠ authorizer` (the agent is the
+ * requester; the human-authored mandate is the authorizer).
+ *
+ * Spec: docs/specs/coordination-mandate.md (§4 concrete shape). The first mandate's
+ * resolved bounds (Justin's A/A/B sign-off, 2026-06-05): cutover stays his manual
+ * click; issuance is dashboard-PIN-gated; the first mandate carries only authorities
+ * 1–2 (exchange-read-credential + sign-code-review), NOT execute-cutover.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/coordination/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/coordination/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/core/ApprovalLedger.d.ts

@@ -0,0 +1,132 @@
+/**
+ * ApprovalLedger — the durable, signed, append-only record of every operator
+ * approval decision, and the per-class agreement ratios computed from it.
+ *
+ * This is Phase 2 of the approved "Approval-as-Data" spec
+ * (`docs/specs/AUTONOMOUS-OPERATION-JUDGMENT-AND-APPROVAL-AS-DATA-SPEC.md`, Part B):
+ * an approval stops being a one-shot "approved" with no memory and becomes data —
+ * recorded as `approved-as-is` vs `approved-with-change` vs `rejected`, with the
+ * WHY of each divergence, so we can (a) see per decision-class where the operator
+ * agrees with the agent's recommendation as-is vs revises it, (b) trend toward
+ * approved-as-is by folding recurring divergences back into design guidance, and
+ * (c) — once a class's ratio holds — pilot auto-approval for that class (Phase 3).
+ *
+ * SCOPE (operator extension, 2026-06-05): the original spec tracked only official
+ * SPEC sign-offs. Justin extended it to track ALL approvals wherever they occur —
+ * a spec sign-off, a decision presented and approved in chat, or any other surface.
+ * Hence `subject`/`decisionClass`/`surface` (general) rather than `specSlug`/
+ * `specClass`, and the spec-only fields (`reviewIterations`/`commitSha`/`evidenceRef`)
+ * are optional — a chat approval simply omits them.
+ *
+ * Mirrors `SessionPoolE2EResultStore` exactly (signed, append-only, tamper-evident,
+ * torn-line-tolerant). The store is signer-agnostic — `sign`/`verifySig` are injected
+ * — so tests use an Ed25519 keypair and production uses an HMAC over the state secret.
+ *
+ * AUTHORITY INVARIANT (spec B1, load-bearing for correctness — NOT just integrity):
+ * for a MANUAL decision the OPERATOR is the authoritative source of `mode` and
+ * `divergences`. The agent must NEVER self-classify the operator's intent. The
+ * writer passes the operator-sourced classification (from the approve control / an
+ * explicit "as-is" vs "with changes: …"); this store records it faithfully. HMAC/
+ * signature guarantees integrity, not correctness — the authoritative-source rule
+ * is what prevents an agent inflating its own agreement ratio. An operator can
+ * dispute and CORRECT any row: a correction is itself an appended, signed row
+ * (`corrects` set), never an in-place edit — history preserved.
+ */
+export type ApprovalMode = 'approved-as-is' | 'approved-with-change' | 'rejected';
+/** Where the approval happened (operator-extension axis — "wherever they occur"). */
+export type ApprovalSurface = 'spec' | 'chat' | 'other';
+export declare const APPROVAL_SURFACES: readonly ApprovalSurface[];
+/** Divergence taxonomy (spec B2). `missing-principle` is a candidate trigger to
+ *  propose a new design principle — a PROPOSAL only, never auto-merged (Part C). */
+export type DivergenceCategory = 'missing-principle' | 'risk-reduction' | 'scope-correction' | 'efficiency' | 'new-information' | 'style';
+export declare const DIVERGENCE_CATEGORIES: readonly DivergenceCategory[];
+export interface Divergence {
+    category: DivergenceCategory;
+    /** One-line what-changed. */
+    summary: string;
+    /** Why the operator changed it — the signal we fold back into design guidance. */
+    why: string;
+}
+export interface ApprovalRecord {
+    /** What was approved — a spec slug, or a stable id for a chat recommendation. */
+    subject: string;
+    /** The bucket the ratio is computed per (e.g. 'governance-safety', 'design-decision'). */
+    decisionClass: string;
+    /** Where the approval occurred. */
+    surface: ApprovalSurface;
+    decidedAt: string;
+    /** 'justin' for a manual decision; 'auto' for an auto-approval (Phase 3). */
+    approver: string;
+    mode: ApprovalMode;
+    /** Empty when approved-as-is; one entry per operator-stated change otherwise. */
+    divergences: Divergence[];
+    /** Spec-context fields — optional (a chat approval omits them). */
+    reviewIterations?: number;
+    commitSha?: string;
+    evidenceRef?: string;
+    /** Set when this row CORRECTS a prior row (operator dispute) — the prior subject+decidedAt. */
+    corrects?: string;
+    signature: string;
+}
+export type ApprovalRecordInput = Omit<ApprovalRecord, 'signature' | 'decidedAt' | 'divergences'> & {
+    decidedAt?: string;
+    divergences?: Divergence[];
+};
+export interface ApprovalLedgerDeps {
+    /** Absolute path to the append-only ledger file. */
+    filePath: string;
+    /** Sign the canonical (signature-excluded) row. Production: HMAC over the state secret. */
+    sign: (canonical: string) => string;
+    /** Verify a signature against the canonical row. */
+    verifySig: (canonical: string, signature: string) => boolean;
+    now?: () => number;
+}
+/** Eligibility knobs for `autoApprovalEligible` (a read-only SIGNAL; never gates here). */
+export interface EligibilityPolicy {
+    /** Minimum approved-as-is ratio for a class to be auto-approval-eligible. */
+    minRatio: number;
+    /** Minimum CURRENT consecutive approved-as-is streak. */
+    minStreak: number;
+    /** Minimum total decisions in the class (don't qualify on a tiny sample). */
+    minTotal: number;
+}
+export declare const DEFAULT_ELIGIBILITY: EligibilityPolicy;
+export interface ClassSummary {
+    decisionClass: string;
+    total: number;
+    approvedAsIs: number;
+    approvedWithChange: number;
+    rejected: number;
+    /** approvedAsIs / total (0 when total is 0). */
+    ratio: number;
+    /** CURRENT consecutive approved-as-is run (most recent rows), reset to 0 by any
+     *  approved-with-change or rejected (spec B3). */
+    streak: number;
+    autoApprovalEligible: boolean;
+    /** Aggregate divergence-category counts for the class (drives the Phase-3 digest). */
+    divergenceCounts: Record<DivergenceCategory, number>;
+}
+/** Canonical bytes a row's signature covers — field-ordered, signature EXCLUDED.
+ *  Optional fields are normalized so a present-vs-absent field is unambiguous, and
+ *  divergences are flattened deterministically so reordering is detectable. */
+export declare function canonicalApprovalRow(r: Omit<ApprovalRecord, 'signature'>): string;
+export declare class ApprovalLedger {
+    private readonly d;
+    constructor(deps: ApprovalLedgerDeps);
+    /**
+     * Append a signed approval row. The `mode` + `divergences` MUST be operator-sourced
+     * (the authority invariant above) — this method does not infer them.
+     * Throws on an internally-inconsistent row so a malformed record can't pollute ratios.
+     */
+    recordApproval(input: ApprovalRecordInput): ApprovalRecord;
+    /** All rows (oldest→newest). Tolerant of a missing file / a torn trailing line. */
+    all(): ApprovalRecord[];
+    /** Verify a row's signature (tamper check). */
+    verify(row: ApprovalRecord): boolean;
+    /** Per-class agreement summary. Read-only; never gates by itself (spec B3). */
+    summarize(policy?: EligibilityPolicy): ClassSummary[];
+    /** Summary for one class (returns a zeroed summary if the class has no rows). */
+    summaryForClass(decisionClass: string, policy?: EligibilityPolicy): ClassSummary;
+    private summarizeRows;
+}
+//# sourceMappingURL=ApprovalLedger.d.ts.map

package/dist/core/ApprovalLedger.d.ts.map

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

package/dist/core/ApprovalLedger.js

@@ -0,0 +1,191 @@
+/**
+ * ApprovalLedger — the durable, signed, append-only record of every operator
+ * approval decision, and the per-class agreement ratios computed from it.
+ *
+ * This is Phase 2 of the approved "Approval-as-Data" spec
+ * (`docs/specs/AUTONOMOUS-OPERATION-JUDGMENT-AND-APPROVAL-AS-DATA-SPEC.md`, Part B):
+ * an approval stops being a one-shot "approved" with no memory and becomes data —
+ * recorded as `approved-as-is` vs `approved-with-change` vs `rejected`, with the
+ * WHY of each divergence, so we can (a) see per decision-class where the operator
+ * agrees with the agent's recommendation as-is vs revises it, (b) trend toward
+ * approved-as-is by folding recurring divergences back into design guidance, and
+ * (c) — once a class's ratio holds — pilot auto-approval for that class (Phase 3).
+ *
+ * SCOPE (operator extension, 2026-06-05): the original spec tracked only official
+ * SPEC sign-offs. Justin extended it to track ALL approvals wherever they occur —
+ * a spec sign-off, a decision presented and approved in chat, or any other surface.
+ * Hence `subject`/`decisionClass`/`surface` (general) rather than `specSlug`/
+ * `specClass`, and the spec-only fields (`reviewIterations`/`commitSha`/`evidenceRef`)
+ * are optional — a chat approval simply omits them.
+ *
+ * Mirrors `SessionPoolE2EResultStore` exactly (signed, append-only, tamper-evident,
+ * torn-line-tolerant). The store is signer-agnostic — `sign`/`verifySig` are injected
+ * — so tests use an Ed25519 keypair and production uses an HMAC over the state secret.
+ *
+ * AUTHORITY INVARIANT (spec B1, load-bearing for correctness — NOT just integrity):
+ * for a MANUAL decision the OPERATOR is the authoritative source of `mode` and
+ * `divergences`. The agent must NEVER self-classify the operator's intent. The
+ * writer passes the operator-sourced classification (from the approve control / an
+ * explicit "as-is" vs "with changes: …"); this store records it faithfully. HMAC/
+ * signature guarantees integrity, not correctness — the authoritative-source rule
+ * is what prevents an agent inflating its own agreement ratio. An operator can
+ * dispute and CORRECT any row: a correction is itself an appended, signed row
+ * (`corrects` set), never an in-place edit — history preserved.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export const APPROVAL_SURFACES = ['spec', 'chat', 'other'];
+export const DIVERGENCE_CATEGORIES = [
+    'missing-principle', 'risk-reduction', 'scope-correction',
+    'efficiency', 'new-information', 'style',
+];
+export const DEFAULT_ELIGIBILITY = { minRatio: 0.9, minStreak: 5, minTotal: 5 };
+/** Canonical bytes a row's signature covers — field-ordered, signature EXCLUDED.
+ *  Optional fields are normalized so a present-vs-absent field is unambiguous, and
+ *  divergences are flattened deterministically so reordering is detectable. */
+export function canonicalApprovalRow(r) {
+    return JSON.stringify([
+        r.subject,
+        r.decisionClass,
+        r.surface,
+        r.decidedAt,
+        r.approver,
+        r.mode,
+        r.divergences.map((d) => [d.category, d.summary, d.why]),
+        r.reviewIterations ?? null,
+        r.commitSha ?? '',
+        r.evidenceRef ?? '',
+        r.corrects ?? '',
+    ]);
+}
+function emptyDivergenceCounts() {
+    return {
+        'missing-principle': 0, 'risk-reduction': 0, 'scope-correction': 0,
+        'efficiency': 0, 'new-information': 0, 'style': 0,
+    };
+}
+export class ApprovalLedger {
+    d;
+    constructor(deps) {
+        this.d = deps;
+    }
+    /**
+     * Append a signed approval row. The `mode` + `divergences` MUST be operator-sourced
+     * (the authority invariant above) — this method does not infer them.
+     * Throws on an internally-inconsistent row so a malformed record can't pollute ratios.
+     */
+    recordApproval(input) {
+        const divergences = input.divergences ?? [];
+        // Consistency guards (correctness, not just integrity).
+        if (input.mode === 'approved-as-is' && divergences.length > 0) {
+            throw new Error('ApprovalLedger: approved-as-is rows must have no divergences (spec B1).');
+        }
+        if (input.mode !== 'approved-as-is' && divergences.length === 0) {
+            // A change/reject with no stated divergence loses the WHY we exist to capture.
+            throw new Error(`ApprovalLedger: mode "${input.mode}" requires at least one divergence with a why.`);
+        }
+        if (!APPROVAL_SURFACES.includes(input.surface)) {
+            throw new Error(`ApprovalLedger: unknown surface "${input.surface}".`);
+        }
+        for (const dv of divergences) {
+            if (!DIVERGENCE_CATEGORIES.includes(dv.category)) {
+                throw new Error(`ApprovalLedger: unknown divergence category "${dv.category}".`);
+            }
+            if (!dv.summary?.trim() || !dv.why?.trim()) {
+                throw new Error('ApprovalLedger: each divergence needs a non-empty summary AND why.');
+            }
+        }
+        const decidedAt = input.decidedAt
+            ?? new Date(this.d.now ? this.d.now() : Date.now()).toISOString();
+        const unsigned = {
+            subject: input.subject,
+            decisionClass: input.decisionClass,
+            surface: input.surface,
+            decidedAt,
+            approver: input.approver,
+            mode: input.mode,
+            divergences,
+            ...(input.reviewIterations != null ? { reviewIterations: input.reviewIterations } : {}),
+            ...(input.commitSha ? { commitSha: input.commitSha } : {}),
+            ...(input.evidenceRef ? { evidenceRef: input.evidenceRef } : {}),
+            ...(input.corrects ? { corrects: input.corrects } : {}),
+        };
+        const row = { ...unsigned, signature: this.d.sign(canonicalApprovalRow(unsigned)) };
+        fs.mkdirSync(path.dirname(this.d.filePath), { recursive: true });
+        fs.appendFileSync(this.d.filePath, JSON.stringify(row) + '\n');
+        return row;
+    }
+    /** All rows (oldest→newest). Tolerant of a missing file / a torn trailing line. */
+    all() {
+        let content;
+        try {
+            content = fs.readFileSync(this.d.filePath, 'utf8');
+        }
+        catch { /* @silent-fallback-ok — ledger file may not exist yet; empty history is the natural default */
+            return [];
+        }
+        const out = [];
+        for (const line of content.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* @silent-fallback-ok — torn-trailing-line tolerance; a crash mid-append must not poison reads */ }
+        }
+        return out;
+    }
+    /** Verify a row's signature (tamper check). */
+    verify(row) {
+        const { signature, ...unsigned } = row;
+        return this.d.verifySig(canonicalApprovalRow(unsigned), signature);
+    }
+    /** Per-class agreement summary. Read-only; never gates by itself (spec B3). */
+    summarize(policy = DEFAULT_ELIGIBILITY) {
+        const byClass = new Map();
+        for (const r of this.all()) {
+            const arr = byClass.get(r.decisionClass) ?? [];
+            arr.push(r);
+            byClass.set(r.decisionClass, arr);
+        }
+        const summaries = [];
+        for (const [decisionClass, rows] of byClass) {
+            summaries.push(this.summarizeRows(decisionClass, rows, policy));
+        }
+        // Stable order: highest-total class first, then alphabetical.
+        summaries.sort((a, b) => b.total - a.total || a.decisionClass.localeCompare(b.decisionClass));
+        return summaries;
+    }
+    /** Summary for one class (returns a zeroed summary if the class has no rows). */
+    summaryForClass(decisionClass, policy = DEFAULT_ELIGIBILITY) {
+        const rows = this.all().filter((r) => r.decisionClass === decisionClass);
+        return this.summarizeRows(decisionClass, rows, policy);
+    }
+    summarizeRows(decisionClass, rows, policy) {
+        let approvedAsIs = 0, approvedWithChange = 0, rejected = 0;
+        const divergenceCounts = emptyDivergenceCounts();
+        for (const r of rows) {
+            if (r.mode === 'approved-as-is')
+                approvedAsIs++;
+            else if (r.mode === 'approved-with-change')
+                approvedWithChange++;
+            else
+                rejected++;
+            for (const dv of r.divergences)
+                divergenceCounts[dv.category]++;
+        }
+        const total = rows.length;
+        const ratio = total === 0 ? 0 : approvedAsIs / total;
+        // CURRENT streak: trailing consecutive approved-as-is from the most-recent row.
+        let streak = 0;
+        for (let i = rows.length - 1; i >= 0; i--) {
+            if (rows[i].mode === 'approved-as-is')
+                streak++;
+            else
+                break;
+        }
+        const autoApprovalEligible = total >= policy.minTotal && ratio >= policy.minRatio && streak >= policy.minStreak;
+        return { decisionClass, total, approvedAsIs, approvedWithChange, rejected, ratio, streak, autoApprovalEligible, divergenceCounts };
+    }
+}
+//# sourceMappingURL=ApprovalLedger.js.map

package/dist/core/ApprovalLedger.js.map

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

package/dist/core/SessionBuildContextStore.d.ts

@@ -0,0 +1,33 @@
+import { execFileSync } from 'node:child_process';
+import type { StateManager } from './StateManager.js';
+export declare const DEFAULT_BUILD_CONTEXT_MAX_AGE_MS: number;
+export interface SessionBuildContextEntry {
+    spawnCwd: string;
+    currentCwd: string;
+    branch?: string;
+    updatedAt: number;
+}
+export type SessionBuildContextState = Record<string, SessionBuildContextEntry>;
+export interface SessionBuildContextRestore {
+    entry: SessionBuildContextEntry;
+    note: string;
+}
+export declare function isEligibleBuildContextCwd(spawnCwd: string, currentCwd: string): boolean;
+export declare function formatBuildContextRestoreNote(entry: SessionBuildContextEntry): string;
+export declare class SessionBuildContextStore {
+    private readonly state;
+    private readonly opts;
+    constructor(state: StateManager, opts?: {
+        now?: () => number;
+        execFileSync?: typeof execFileSync;
+        maxAgeMs?: number;
+    });
+    record(tmuxSession: string, spawnCwd: string, currentCwd: string): void;
+    getRestore(tmuxSession: string): SessionBuildContextRestore | null;
+    readAll(): SessionBuildContextState;
+    private writeAll;
+    private readBranch;
+    private now;
+    private maxAgeMs;
+}
+//# sourceMappingURL=SessionBuildContextStore.d.ts.map

package/dist/core/SessionBuildContextStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionBuildContextStore.d.ts","sourceRoot":"","sources":["../../src/core/SessionBuildContextStore.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD,eAAO,MAAM,gCAAgC,QAAqB,CAAC;AAEnE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;AAEhF,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,wBAAwB,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAMvF;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,CASrF;AAED,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADJ,KAAK,EAAE,YAAY,EACnB,IAAI,GAAE;QACrB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;QACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;KACd;IAGR,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAqBvE,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,0BAA0B,GAAG,IAAI;IASlE,OAAO,IAAI,wBAAwB;IAsBnC,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAgBlB,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,QAAQ;CAGjB"}

package/dist/core/SessionBuildContextStore.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+const STATE_KEY = 'session-build-context';
+export const DEFAULT_BUILD_CONTEXT_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+export function isEligibleBuildContextCwd(spawnCwd, currentCwd) {
+    if (!spawnCwd || !currentCwd)
+        return false;
+    const spawn = path.resolve(spawnCwd);
+    const current = path.resolve(currentCwd);
+    if (spawn === current)
+        return false;
+    return current.split(path.sep).includes('.worktrees');
+}
+export function formatBuildContextRestoreNote(entry) {
+    const branchLine = entry.branch ? `  branch:   ${entry.branch}\n` : '';
+    return [
+        '[BUILD-CONTEXT RESTORE] Before this restart you were building in:',
+        `  worktree: ${entry.currentCwd}`,
+        branchLine ? branchLine.trimEnd() : null,
+        `Your shell is back in ${entry.spawnCwd} after the restart — cd ${entry.currentCwd} before continuing your build.`,
+        'Do NOT start over in agent-home; your work is in that worktree.',
+    ].filter((line) => line != null).join('\n');
+}
+export class SessionBuildContextStore {
+    state;
+    opts;
+    constructor(state, opts = {}) {
+        this.state = state;
+        this.opts = opts;
+    }
+    record(tmuxSession, spawnCwd, currentCwd) {
+        const now = this.now();
+        const all = this.readAll();
+        const prior = all[tmuxSession];
+        const normalizedSpawn = path.resolve(spawnCwd);
+        const normalizedCurrent = path.resolve(currentCwd);
+        if (prior?.spawnCwd === normalizedSpawn && prior.currentCwd === normalizedCurrent) {
+            return;
+        }
+        const branch = this.readBranch(normalizedCurrent);
+        all[tmuxSession] = {
+            spawnCwd: normalizedSpawn,
+            currentCwd: normalizedCurrent,
+            ...(branch ? { branch } : {}),
+            updatedAt: now,
+        };
+        this.writeAll(all);
+    }
+    getRestore(tmuxSession) {
+        const entry = this.readAll()[tmuxSession];
+        if (!entry)
+            return null;
+        if (!isEligibleBuildContextCwd(entry.spawnCwd, entry.currentCwd))
+            return null;
+        if (this.now() - entry.updatedAt > this.maxAgeMs())
+            return null;
+        if (!fs.existsSync(entry.currentCwd))
+            return null;
+        return { entry, note: formatBuildContextRestoreNote(entry) };
+    }
+    readAll() {
+        const raw = this.state.get(STATE_KEY);
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            return {};
+        const out = {};
+        for (const [key, value] of Object.entries(raw)) {
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                continue;
+            const entry = value;
+            if (typeof entry.spawnCwd !== 'string'
+                || typeof entry.currentCwd !== 'string'
+                || typeof entry.updatedAt !== 'number')
+                continue;
+            out[key] = {
+                spawnCwd: entry.spawnCwd,
+                currentCwd: entry.currentCwd,
+                ...(typeof entry.branch === 'string' && entry.branch.trim() ? { branch: entry.branch } : {}),
+                updatedAt: entry.updatedAt,
+            };
+        }
+        return out;
+    }
+    writeAll(state) {
+        this.state.set(STATE_KEY, state);
+    }
+    readBranch(cwd) {
+        if (!fs.existsSync(cwd))
+            return null;
+        try {
+            const out = (this.opts.execFileSync ?? execFileSync)('git', ['-C', cwd, 'branch', '--show-current'], { encoding: 'utf-8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] });
+            const branch = String(out).trim();
+            return branch || null;
+        }
+        catch {
+            // @silent-fallback-ok — branch name is best-effort enrichment; cwd restore still works without it.
+            return null;
+        }
+    }
+    now() {
+        return this.opts.now?.() ?? Date.now();
+    }
+    maxAgeMs() {
+        return this.opts.maxAgeMs ?? DEFAULT_BUILD_CONTEXT_MAX_AGE_MS;
+    }
+}
+//# sourceMappingURL=SessionBuildContextStore.js.map

package/dist/core/SessionBuildContextStore.js.map

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

package/dist/core/SessionManager.d.ts

@@ -163,6 +163,7 @@ export declare class SessionManager extends EventEmitter {
     private _cachedRunningSessions;
     /** Worktree manager — when set, spawnSession resolves an isolated worktree per topic. */
     private worktreeManager;
+    private buildContextStore;
     /** Per-session shim directory root (one subdir per session). Used for K9 mandatory shim. */
     private shimRoot;
     constructor(config: SessionManagerConfig, state: StateManager);
@@ -533,6 +534,9 @@ export declare class SessionManager extends EventEmitter {
      * Capture the current output of a tmux session.
      */
     captureOutput(tmuxSession: string, lines?: number): string | null;
+    private currentPaneCwd;
+    private recordBuildContext;
+    private withBuildContextRestoreNote;
     /**
      * Resolve the IntelligenceFramework a tmux session was spawned under
      * by reading the INSTAR_FRAMEWORK env we set in its tmux env block.