@buildaharness/aielia 0.3.0

package/dist/lexical/patterns.d.ts

@@ -0,0 +1,64 @@
+export interface FactMarkerPatterns {
+    factMarkers: RegExp[];
+    healthOrDietaryMarkers: RegExp[];
+    durableNameOrPreferenceMarkers: RegExp[];
+    nonClaimMarkers: RegExp[];
+    clauseBoundary: RegExp[];
+}
+/** Matches fact-extraction.ts's FACT_MARKERS/HEALTH_OR_DIETARY_MARKERS/etc. — one compiled pattern per language. */
+export declare function getFactMarkerPatterns(): FactMarkerPatterns;
+/** True if `text` matches any of `patterns` — the "try every language, gate on either matching" rule (Decision 3). */
+export declare function testAny(patterns: RegExp[], text: string): boolean;
+/** Splits `text` on the first pattern (by language) that isn't empty-matching — clause boundaries don't need multi-language OR-ing the way a match test does, since splitting on any one language's boundary set is enough to separate clauses regardless of which language the boundary word came from. Currently just "en"; see splitClausesAcrossLanguages if a future language needs a genuinely different boundary shape combined in the same split. */
+export declare function splitOnAny(patterns: RegExp[], text: string): string[];
+export interface CompiledRiskPattern {
+    pattern: RegExp;
+    reason: string;
+}
+export interface RiskPatterns {
+    highRiskPatterns: CompiledRiskPattern[];
+    mediumRiskPatterns: CompiledRiskPattern[];
+    reminderPattern: CompiledRiskPattern;
+    reminderRecallQuestion: RegExp[];
+    bulkReminderReason: string;
+    pastTenseQuestion: RegExp[];
+    firstPersonPastNarrative: RegExp[];
+    reportedThirdPartySpeech: RegExp[];
+    riskClauseBoundary: RegExp[];
+}
+/** Matches risk-classifier.ts's HIGH_RISK_PATTERNS/MEDIUM_RISK_PATTERNS/REMINDER_PATTERN/etc. */
+export declare function getRiskPatterns(): RiskPatterns;
+/** Matches trust-tagging.ts's INJECTION_PATTERNS. */
+export declare function getInjectionPatterns(): CompiledRiskPattern[];
+/** Matches contradiction-checker.ts's CODING_FACT_MARKERS. */
+export declare function getCodingFactMarkerPatterns(): RegExp[];
+export interface EnumerationPatterns {
+    sequencingMarkers: RegExp[];
+    oneCommaListMarker: RegExp[];
+    twoCommaListMarker: RegExp[];
+    semicolonListMarker: RegExp[];
+    numberedListItem: RegExp[];
+    factThenSingleReminder: RegExp[];
+    remindWord: RegExp[];
+}
+/** Matches decomposition-classifier.ts's SEQUENCING_MARKERS/ONE_COMMA_LIST_MARKER/etc. */
+export declare function getEnumerationPatterns(): EnumerationPatterns;
+export interface TaskCancelPatterns {
+    taskCancelVerbs: RegExp[];
+    taskReferenceMarker: RegExp[];
+    cancelMatchStopwords: ReadonlySet<string>;
+}
+/** Matches plan-store.ts's TASK_CANCEL_VERBS/TASK_REFERENCE_MARKER/CANCEL_MATCH_STOPWORDS. */
+export declare function getTaskCancelPatterns(): TaskCancelPatterns;
+export interface PlanModeCancelPatterns {
+    cancelVerbs: RegExp[];
+    planningReferenceMarker: RegExp[];
+}
+/** Matches plan-drafting-service.ts's exit-phrase detection ("cancel plan"/"abort planning"/...) — both a cancel-shaped verb AND an explicit reference to planning/drafting must match, same both-markers-required discipline getTaskCancelPatterns uses, so an unrelated "cancel my flight" said mid-draft doesn't spuriously exit plan mode. */
+export declare function getPlanModeCancelPatterns(): PlanModeCancelPatterns;
+/** Matches batch-list-detector.ts's CONNECTOR_WORDS. */
+export declare function getConnectorWords(): ReadonlySet<string>;
+/** Matches tool-yield-classifier.ts's DEAD_END_MARKERS. */
+export declare function getDeadEndMarkers(): RegExp[];
+/** Matches plan-templates/index.ts's TEMPLATE_KEYWORDS. */
+export declare function getTemplateKeywords(): Record<string, string[]>;

package/dist/memory-service.d.ts

@@ -0,0 +1,219 @@
+import { ExperienceStore, StrategyWeightKey, DecompositionEntry, RecoverySequenceEntry, ExperienceStoreData, ExternalContradictionInput } from '@buildaharness/harness';
+import { MemoryAdapter, ReminderStore, ReminderRecord, ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { UserFact } from './fact-extraction.js';
+import { Corroboration } from './contradiction-checker.js';
+import { StatedFact, FactCategory } from './turn-intent-classifier.js';
+export declare const FACT_CAP = 20;
+export declare const DURABLE_FACTS_KEY = "facts:durable";
+/**
+ * Global, never cleared by `/new` — same retention shape as DURABLE_FACTS_KEY (a pending fact
+ * shouldn't vanish just because the session changed). Phase 3 of
+ * plans/personal_assistant_fact_extraction_llm_confidence_plan.html: a `model_inferred` fact
+ * that reached `durable: true, confidence: 'medium'` lands here instead of being silently
+ * promoted or silently dropped — see `recordFacts()`'s promotion policy and
+ * `confirmPendingFact()`/`rejectPendingFact()` below.
+ */
+export declare const PENDING_CONFIRMATION_KEY = "facts:pending-confirmation";
+/**
+ * Global, never cleared by `/new`. Holds facts removed from `facts:${sessionId}`/
+ * PENDING_CONFIRMATION_KEY either by an entry-time retraction (a later statement contradicts an
+ * unconfirmed guess — see `recordFacts()`) or by an explicit `/memory reject`. Rejected facts are
+ * remembered, not blacklisted: the entry-time check compares new statements against this pool
+ * too, so a matching restatement can re-enter PENDING_CONFIRMATION_KEY tagged
+ * `previouslyRejected` instead of being silently re-asked forever or silently refused forever.
+ */
+export declare const REJECTED_FACTS_KEY = "facts:rejected";
+/** Bound on how many learned decompositions/recovery sequences `getMemorySummary()` includes — see MemorySummary's doc comment. */
+export declare const MEMORY_SUMMARY_PREVIEW_LIMIT = 20;
+/** A `model_inferred` fact sitting in PENDING_CONFIRMATION_KEY, awaiting `/memory confirm`/`/memory reject`. */
+export interface PendingFact extends UserFact {
+    category: FactCategory;
+    /** True when this exact fact previously lived in REJECTED_FACTS_KEY and was corroborated back in by a later, differently-phrased restatement — see `recordFacts()`'s corroboration handling. `/memory` surfaces this so the user sees the prior rejection instead of the fact looking brand new. */
+    previouslyRejected?: boolean;
+}
+/** An entry in REJECTED_FACTS_KEY — see that constant's doc comment. */
+export interface RejectedFact {
+    text: string;
+    rejectedAt: string;
+    rejectionSource: 'auto_retracted' | 'user_explicit';
+}
+/**
+ * Read-only snapshot returned by `getMemorySummary()` — see that method's doc comment.
+ * `decompositions`/`recoverySequences` are capped at the 20 most recently learned entries
+ * (newest first) so `/memory` stays scannable after months of accumulated learning; `/memory
+ * export` (see `exportMemory()`) returns every category unbounded, since a file on disk doesn't
+ * have the same terminal-scrollback concern a REPL print does. `pending`/`rejected` are their
+ * stores' full, unbounded contents — neither is expected to grow anywhere near
+ * MEMORY_SUMMARY_PREVIEW_LIMIT in practice, unlike decompositions/recoverySequences.
+ */
+export interface MemorySummary {
+    facts: UserFact[];
+    reminders: ReminderRecord[];
+    pending: PendingFact[];
+    experience: {
+        strategyWeights: Record<StrategyWeightKey, number>;
+        decompositions: DecompositionEntry[];
+        recoverySequences: RecoverySequenceEntry[];
+    };
+}
+/** Full, unbounded snapshot written by `/memory export` — every ExperienceStore category plus facts/reminders/pending-confirmation, as plain JSON. */
+export interface MemoryExport {
+    exportedAt: string;
+    facts: UserFact[];
+    reminders: ReminderRecord[];
+    pending: PendingFact[];
+    experience: ExperienceStoreData;
+}
+/** Result of a single fact's promotion-time (`/memory confirm`) or corroboration-driven (medium→high) admission into DURABLE_FACTS_KEY — see `confirmPendingFact()`. */
+export interface PendingConfirmationOutcome {
+    fact: UserFact;
+    /** Set when the promotion-time check (checkForContradictions against current Knowledge) found a conflict — advisory only, matching every other contradiction check in this codebase: the promotion still succeeds regardless. */
+    conflictNotice?: string;
+}
+/** `recordFacts()`'s return — see its doc comment's "Ordering constraint" note on why callers must read this before building any contradiction notice for the turn. */
+export interface RecordFactsResult {
+    contradictions: ExternalContradictionInput[];
+    corroborations: Corroboration[];
+}
+/**
+ * The exact lexical+LLM merge `recordFacts()` uses to decide what to write to the fact stores,
+ * exposed (Phase 4 of plans/personal_assistant_fact_extraction_llm_confidence_plan.html) so a
+ * caller can seed `HarnessRunParams.currentTurnFacts` (harness-bridge.ts's `factExtractor`) with
+ * the identical merged, deduplicated list — instead of harness-bridge.ts recomputing only the free
+ * lexical half and never seeing an LLM-caught fact at all, which left a same-turn LLM-caught fact
+ * invisible to contradiction detection. Two independent calls with the same arguments (one here to
+ * build a harness run's currentTurnFacts before the run, one inside `recordFacts()` itself after
+ * it) each stamp their own `extractedAt` — harmless, since neither call's result is compared
+ * against the other's by identity.
+ */
+export declare function buildTurnFacts(sessionId: string, userMessage: string, statedFacts: StatedFact[]): UserFact[];
+/**
+ * Owns fact/reminder/experience reads that feed each turn's system prompt, fact capture, and the
+ * `/memory`/`/memory export` read-only snapshots — the "what has this assistant learned" surface
+ * of PersonalAssistant, split out in Phase 4d of the architecture remediation plan. `llmClient`/
+ * `model` were added in Phase 3 of the fact-extraction-confidence plan — `recordFacts()`'s
+ * entry-time consistency check and the promotion-time check in `confirmPendingFact()` both run
+ * the same `checkForContradictions` the harness's own per-turn contradiction hook already uses,
+ * rather than building a second mechanism.
+ */
+export declare class MemoryService {
+    private readonly memory;
+    private readonly reminderStore;
+    private readonly experienceStore;
+    private readonly llmClient;
+    private readonly model;
+    /** Resolves to `config.activeProject` if the user set one via `/project <name>`, else the workspace root — read through a getter (same convention as `model` above) so a mid-session `/project`/`/config set activeProject` change takes effect on the very next turn. See UserFact.project's doc comment for how this is used. */
+    private readonly currentProject;
+    constructor(memory: MemoryAdapter, reminderStore: ReminderStore, experienceStore: ExperienceStore, llmClient: ILLMClient, model: () => string | undefined, 
+    /** Resolves to `config.activeProject` if the user set one via `/project <name>`, else the workspace root — read through a getter (same convention as `model` above) so a mid-session `/project`/`/config set activeProject` change takes effect on the very next turn. See UserFact.project's doc comment for how this is used. */
+    currentProject?: () => string);
+    /**
+     * Durable + session facts for `sessionId`, plus the ready-to-splice system-prompt block — see
+     * runTurn's former factsBlock. `facts` is the full inventory, unfiltered by project — `/memory`
+     * (getMemorySummary) needs to show and let the user forget a fact regardless of which project is
+     * currently active. `factsBlock` — what the model actually sees this turn — filters to
+     * global-or-current-project only, so an unrelated project's facts don't leak into context (see
+     * UserFact.project's doc comment).
+     */
+    loadFacts(sessionId: string): Promise<{
+        facts: UserFact[];
+        factsBlock: string;
+    }>;
+    /**
+     * `/memory forget <n>` — removes the nth entry (1-based in `/memory`'s "Facts I know" display,
+     * 0-based here) from whichever store(s) it actually lives in. `index` is over the same merged,
+     * durable-first ordering `loadFacts()`/`getMemorySummary()` already produce, so the number a user
+     * sees in `/memory` is the number they pass here — no separate "durable index" vs "session index"
+     * to track. A fact that's both durable and session-scoped under an identical restated text (see
+     * mergeFacts's dedup) is removed from both stores by `sameFact` identity, not just the copy that
+     * happened to win the display dedup. Returns undefined for an out-of-range index (the caller's
+     * `/memory` view is stale — nothing to forget).
+     */
+    forgetFact(index: number, sessionId: string): Promise<UserFact | undefined>;
+    /**
+     * reminderStore is cross-session durable (clearSession() never touches it, same tier as
+     * DURABLE_FACTS_KEY) but, unlike facts, was never actually surfaced into context: a plain
+     * conversational question about a previously-created reminder ("did I mention X earlier?") got
+     * no grounding unless the model happened to call list_reminders itself — found via live
+     * testing (a fresh /new session flatly denied any record of a reminder created in the prior
+     * session, and separately claimed "I don't have access to other conversations" in the same
+     * reply that a durable *fact* from that same prior session correctly informed). Only undone
+     * reminders: a completed one is no longer something the user would expect the assistant to
+     * "remember" as pending.
+     */
+    loadActiveReminders(): Promise<{
+        activeReminders: ReminderRecord[];
+        remindersBlock: string;
+    }>;
+    /**
+     * Captures this turn's durable/session facts into the session's fact store. A no-op when
+     * neither pass finds anything. Facts that clear `shouldAutoPromote()` (see that function's doc
+     * comment for the current three-way policy) are ALSO appended to DURABLE_FACTS_KEY, a store
+     * clearSession() never touches, so they survive /new instead of vanishing with the rest of the
+     * session's facts. A `model_inferred` fact at `durable: true, confidence: 'medium'` is queued
+     * to PENDING_CONFIRMATION_KEY instead (Phase 3) — never auto-promoted, never dropped.
+     *
+     * Phase 2: the free lexical pass (`extractFactsFromTurn`) and `classifyTurnIntent`'s
+     * `statesDurableFacts` (the `StatedFact[]` list this method's `statedFacts` param carries) are
+     * **both always considered**, merged via `mergeTurnFacts()`. The lexical pass keeps running
+     * unconditionally so a classifier outage (an empty `statedFacts` list, per
+     * `failSafeClassification`) still degrades to "regex only," never to "no facts at all."
+     *
+     * Phase 3: every write this function performs passes through the entry-time consistency check
+     * first — this turn's new facts are checked, in one batched `checkForContradictions` call, both
+     * against Knowledge (durable + session facts already in the Knowledge tier — see
+     * `tierForFact`/`isKnowledgeTier`) and against the session's current medium/low-confidence
+     * `model_inferred` facts (the "uncertain pool"), plus REJECTED_FACTS_KEY (so a restated,
+     * previously-rejected guess is recognized rather than treated as brand new). A contradiction
+     * against the uncertain pool is a retraction: the retracted fact is removed from the session
+     * store and PENDING_CONFIRMATION_KEY and recorded into REJECTED_FACTS_KEY instead. A
+     * corroboration against the uncertain pool upgrades that fact's confidence in place
+     * (low→medium queues it to PENDING_CONFIRMATION_KEY; medium→high promotes it to
+     * DURABLE_FACTS_KEY) — corroboration is deliberately the one read-modify-write path in this
+     * function; every other write is append-only. A corroboration against REJECTED_FACTS_KEY
+     * re-queues the fact to PENDING_CONFIRMATION_KEY tagged `previouslyRejected`.
+     *
+     * **Ordering constraint on callers**: this must run, and its `contradictions` must be folded
+     * into whatever contradiction notice the turn returns, BEFORE that notice is finalized — see
+     * response-service.ts's three result-builders and assistant-session.ts's
+     * `dedupedContradictionNotice`. Left uncalled, this phase's entry-time findings would be
+     * computed but never surfaced in the turn's own reply.
+     */
+    recordFacts(sessionId: string, userMessage: string, statedFacts: StatedFact[], onUsage?: (usage: TokenUsage) => void): Promise<RecordFactsResult>;
+    /**
+     * `/memory confirm <n>` — promotes the nth (1-based in `/memory`'s display, 0-based here) entry
+     * in PENDING_CONFIRMATION_KEY to DURABLE_FACTS_KEY. Runs the same promotion-time check as
+     * corroboration's medium→high path: entering DURABLE_FACTS_KEY is itself a store-write, checked
+     * against current Knowledge at the moment of promotion rather than deferred to the next turn's
+     * re-seed. A conflict is advisory only — the confirm still succeeds regardless, matching every
+     * other contradiction check in this codebase (never gates belief admission); the conflict is
+     * returned as `conflictNotice` for the caller to surface. Returns undefined for an out-of-range
+     * index (the caller's `/memory` view is stale — nothing to confirm).
+     */
+    confirmPendingFact(index: number, onUsage?: (usage: TokenUsage) => void): Promise<PendingConfirmationOutcome | undefined>;
+    /** `/memory reject <n>` — removes the nth pending entry and records it into REJECTED_FACTS_KEY with `rejectionSource: 'user_explicit'`. Returns undefined for an out-of-range index. */
+    rejectPendingFact(index: number): Promise<PendingFact | undefined>;
+    /** `/memory confirm <category>` — bulk-confirms every pending entry in one category, useful once a topic accumulates several related guesses the user would naturally want to resolve together. Runs the promotion-time check per fact (still one call per fact — matches confirmPendingFact's own guarantee, not batched across facts since each is an independent store-write with its own conflict outcome). */
+    confirmPendingCategory(category: FactCategory, onUsage?: (usage: TokenUsage) => void): Promise<PendingConfirmationOutcome[]>;
+    /** `/memory reject <category>` — bulk-rejects every pending entry in one category. */
+    rejectPendingCategory(category: FactCategory): Promise<PendingFact[]>;
+    private rejectFacts;
+    private promoteConfirmedFact;
+    /**
+     * Read-only snapshot of what this session/assistant has learned: durable facts extracted
+     * from the user's own messages, reminders created so far, pending-confirmation guesses, and the
+     * real content (not just counts) of the learning-layer `ExperienceStore` — strategy weights in
+     * full, and the 20 most recently learned decompositions/recovery sequences (see
+     * MEMORY_SUMMARY_PREVIEW_LIMIT). Use `exportMemory()` for the full, unbounded contents. Used by
+     * `/memory`.
+     */
+    getMemorySummary(sessionId: string): Promise<MemorySummary>;
+    /**
+     * Full, unbounded snapshot of everything learned so far — every ExperienceStore category
+     * (not just the 20-entry preview `getMemorySummary()` bounds for terminal display) plus
+     * facts/reminders/pending-confirmation, as plain JSON. Read-only: this adds no corresponding
+     * import path, so a user cannot hand-edit the result and load it back in. Used by `/memory
+     * export`.
+     */
+    exportMemory(sessionId: string): Promise<MemoryExport>;
+}

package/dist/model-pricing.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Static, approximate per-model pricing — a fallback used only by the proxy backend's /cost
+ * display. The proxy (packages/proxy/src/forward.ts) is a thin pass-through to Anthropic/
+ * OpenAI and never computes or returns a dollar cost itself, only the raw token counts each
+ * provider's response already includes. This table is NOT billing-accurate: it doesn't account
+ * for prompt-caching discounts, batch pricing, or any rate change since it was last updated —
+ * update the numbers below if Anthropic's published pricing changes. The Claude CLI backend
+ * needs no such table; its costUsd comes from Claude's own real accounting (see
+ * claude-cli-prompt.ts's parseClaudeCliOutput).
+ */
+export interface ModelPriceUsd {
+    inputPerMTok: number;
+    outputPerMTok: number;
+}
+/** Returns undefined (rather than a misleading number) when the model is unset or not a recognized Claude tier — callers must not silently treat "no estimate" as "free". */
+export declare function estimateCostUsd(model: string | undefined, usage: {
+    inputTokens: number;
+    outputTokens: number;
+}): number | undefined;

package/dist/network-containment.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Node-level network containment for an approved run_shell_command execution — Decision 6 of
+ * plans/lexical_functions_hardening_plan.html (Phase 4 step 2). This is the network-reachability
+ * half of that decision; the env-stripping half already existed in shell-executor.ts's
+ * allowlistedEnv(). Deliberately not a real OS sandbox (see the plan's Decision 6 for why that
+ * tradeoff was chosen): a minimal loopback-only forward proxy that relays a CONNECT tunnel
+ * (HTTPS) or a plain-HTTP proxy request only when its target host matches an entry in the
+ * caller-supplied allowlist (exact match or subdomain), and otherwise closes the connection with
+ * a 403. The spawned subprocess's HTTP(S)_PROXY env vars are forced to point here, so a tool that
+ * honors those (curl, wget, most language HTTP clients) can only reach an allowlisted host. This
+ * does NOT stop a tool that opens raw sockets and ignores proxy env vars entirely — that
+ * limitation is Decision 6's explicitly accepted tradeoff for a dependency-free, Node-only
+ * implementation identical across CLI and desktop.
+ */
+export interface NetworkContainmentProxy {
+    port: number;
+    close: () => Promise<void>;
+}
+export declare function getNetworkContainmentProxy(allowlist: readonly string[]): Promise<NetworkContainmentProxy>;
+/** Test-only: drops all cached proxies so a test's allowlist doesn't leak into another test's expectations. */
+export declare function resetNetworkContainmentProxiesForTests(): Promise<void>;

package/dist/node-config-store.d.ts

@@ -0,0 +1,29 @@
+import { AssistantConfig, ConfigStore } from './config.js';
+/**
+ * JSON-file-backed ConfigStore for the CLI, at a single `config.json` path (typically
+ * `<dataDir>/config.json`). Deliberately not exported from this package's index — only cli.ts
+ * imports it, same reasoning as node-fs-backend.ts — so a browser build never pulls in
+ * node:fs/promises.
+ *
+ * save() merges the patch onto whatever's already persisted (never a blind overwrite of
+ * unrelated keys) and writes through a temp-file-then-rename so a crash mid-write can never
+ * leave a half-written config.json behind — the same failure mode file-tools.ts's
+ * .pending-actions staging already avoids the same way. Setting a key to `undefined` in a
+ * patch removes it from the persisted file (JSON.stringify drops undefined-valued
+ * properties), which is what /config reset relies on.
+ *
+ * Concurrent save() calls on the same instance are serialized through an internal queue —
+ * cli.ts's readline 'line' handler doesn't wait for one command to finish before dispatching
+ * the next (e.g. piped stdin with two /config set lines back to back), so without this a
+ * second save()'s load-modify-write could race the first's: reading stale state before the
+ * first's write lands and silently clobbering it, or (with a timestamp-only temp filename)
+ * colliding on the exact same temp path within the same millisecond.
+ */
+export declare class NodeConfigStore implements ConfigStore {
+    private readonly path;
+    private queue;
+    constructor(path: string);
+    load(): Promise<Partial<AssistantConfig>>;
+    save(patch: Partial<AssistantConfig>): Promise<void>;
+    private writePatch;
+}

package/dist/node-display-names.d.ts

@@ -0,0 +1,26 @@
+import { LayerActivityEvent } from '@buildaharness/harness';
+export declare function nodeDisplayName(node: string | undefined): string | undefined;
+/**
+ * The 11 harness layer slugs, in the fixed order CLAUDE.md's architecture table lists them —
+ * used by both the CLI's `/layers` and chat-ui's layer grid to render a stable 2-3 letter
+ * code per layer (Phase 3.3 of the harness layer activation plan). Matches the `layer` field
+ * on the `layer_activity` TraceEvent (see trace-events.ts) and HarnessRunOptions'
+ * LayerActivityEvent (see @buildaharness/harness).
+ */
+export declare const LAYER_ORDER: readonly ["world_model", "evidence_reasoning", "hypothesis", "contradiction", "diagnostics", "control_state", "planning", "execution", "verification", "recovery", "reviewer_pass"];
+export type LayerSlug = (typeof LAYER_ORDER)[number];
+export declare const LAYER_DISPLAY_NAME: Record<LayerSlug, string>;
+export declare const LAYER_SHORT_CODE: Record<LayerSlug, string>;
+export declare function nodeToLayer(node: string | undefined): LayerSlug | undefined;
+export interface WhyChainItem {
+    layer: LayerSlug;
+    reason: string;
+}
+/**
+ * Collapses a turn's raw layerActivity (one event per layer per main-loop iteration — see
+ * harness-runtime.ts's onLayerActivity doc comment) down to just the layers that fired, in the
+ * order they fired, merging consecutive re-fires of the same layer (back-to-back loop
+ * iterations) into a single link. Shared by the CLI's `/why` and chat-ui's "Why?" panel so both
+ * surfaces summarize a turn identically instead of drifting apart.
+ */
+export declare function buildWhyChain(layerActivity: LayerActivityEvent[]): WhyChainItem[];

package/dist/node-fs-backend.d.ts

@@ -0,0 +1,8 @@
+import { FsBackend } from '@buildaharness/runtime';
+/**
+ * node:fs/promises-backed FsBackend for the CLI. Deliberately not exported from
+ * this package's index — only cli.ts imports it, so a browser build (chat-ui)
+ * that only ever imports the package root never pulls a Node builtin into its
+ * bundle.
+ */
+export declare function createNodeFsBackend(): FsBackend;

package/dist/non-interactive-mode.d.ts

@@ -0,0 +1,22 @@
+export type NonInteractiveApprovalMode = 'decline' | 'require-tty';
+/**
+ * Pure logic backing cli.ts's ASSISTANT_NON_INTERACTIVE_APPROVAL handling — split out so it's
+ * unit-testable in isolation, the same way error-classifier.ts and node-display-names.ts are
+ * split out of cli.ts for the same reason (cli.ts runs `main()` at import time, so it can't be
+ * imported directly by a test).
+ *
+ * Turns the piped/scripted-stdin approval-gate behavior into an explicit, documented choice
+ * instead of an incidental side effect of readline hitting closed stdin (see cli.ts's askYesNo,
+ * whose fail-closed catch stays the unset-env-var default and is unaffected by this — nothing
+ * changes for an interactive TTY session either way). 'decline': every approval gate
+ * auto-declines immediately, without ever touching stdin — the right choice for a scripted/CI
+ * caller that expects every HIGH-risk/staged action to be rejected outright, no exceptions.
+ * 'require-tty': cli.ts fails fast at startup with a clear, actionable error if stdin isn't a
+ * real TTY, instead of running an entire session that can only surface the problem deep in, at
+ * the first approval prompt, as a generic "[could not read a response]". An unrecognized value is
+ * ignored (falls back to unset) with a startup warning, so a typo can't silently produce
+ * different behavior than intended — mirrors ASSISTANT_LLM_BACKEND's own typo-tolerance in
+ * cli-config.ts, but warns here since a silently-ignored approval-mode typo is safety-relevant in
+ * a way a silently-ignored backend typo (which still resolves to a working default) isn't.
+ */
+export declare function resolveNonInteractiveApprovalMode(env: NodeJS.ProcessEnv): NonInteractiveApprovalMode | undefined;

package/dist/one-loop-flag.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure logic backing PersonalAssistant's ASSISTANT_ONE_LOOP handling — split out so it's
+ * unit-testable in isolation, same pattern as control-plane-flag.ts (removed in
+ * personal-assistant: Phase 4b/4c) and non-interactive-mode.ts's resolveNonInteractiveApprovalMode:
+ * a module-level default resolved once from process.env, threaded as an injectable constructor
+ * option so tests never touch real process.env.
+ *
+ * Backs plans/harness_d2_one_loop_rewire_plan.html's R2 phase: the harness-driven proposer that
+ * lets HarnessRuntime's driveMainLoop actually call AgentLoop's tool-calling machinery once per
+ * main-loop iteration, instead of receiving an already-finished draftReply after the fact. R2
+ * landed it default OFF; R3/R4 built the rest of the wiring behind it; R5 gathered the rollout
+ * evidence (Rule 2/Rule 6 differential clean, CLI live-verification both states, the chat-ui
+ * flag OFF/ON parity matrix green under real headless Chromium) and flipped the default to
+ * 'enabled' on 2026-09-06. The flag itself is kept for one more window as an escape hatch before
+ * being removed (R5's final step), mirroring ASSISTANT_CONTROL_PLANE's own shape.
+ *
+ * 'enabled' (the default): HarnessBridge.run() swaps in a real harness-driven proposer (built
+ * from AgentLoop.createHarnessProposer) as the 'default' toolExecutor, when the caller supplies
+ * one — the harness's driveMainLoop drives the real tool calls one iteration at a time.
+ * 'disabled': the pre-rewire behavior — toolExecutors.default always resolves to
+ * `() => draftReply` (the tool loop runs to completion first, the harness sees the finished
+ * reply). An unrecognized value is ignored (falls back to the default) with a startup warning,
+ * same typo-tolerance-with-a-warning convention resolveControlPlaneMode/
+ * resolveNonInteractiveApprovalMode used, since a silently-misread flag here is safety-relevant.
+ */
+export type OneLoopMode = 'enabled' | 'disabled';
+export declare const DEFAULT_ONE_LOOP_MODE: OneLoopMode;
+/**
+ * Value-level resolver, shared by every surface: `resolveOneLoopMode` (CLI, reads
+ * `process.env.ASSISTANT_ONE_LOOP`) and chat-ui's `envOverridesFromImportMetaEnv` (browser build,
+ * reads Vite's `import.meta.env.VITE_ASSISTANT_ONE_LOOP`, which has no `process` to hand a
+ * `NodeJS.ProcessEnv` to). An unset or empty value falls back to the default silently; an
+ * unrecognized non-empty value falls back with a startup warning naming `varName`, the same
+ * typo-tolerance-with-a-warning convention resolveControlPlaneMode/resolveNonInteractiveApprovalMode
+ * use, since a silently-misread flag here is safety-relevant.
+ */
+export declare function normalizeOneLoopMode(raw: string | undefined, varName?: string): OneLoopMode;
+export declare function resolveOneLoopMode(env: NodeJS.ProcessEnv): OneLoopMode;

package/dist/plan-approval-service.d.ts

@@ -0,0 +1,62 @@
+import { AssistantSession } from './assistant-session.js';
+import { PlanService } from './plan-service.js';
+import { PlanRecord } from './plan-store.js';
+import { AssistantTurnResult } from './assistant-types.js';
+import { TraceEvent } from './trace-events.js';
+/**
+ * `'approve_trusted'` (plan mode's P10) is structurally its own decision, not a modifier on
+ * `'approve'`/`'approve_with_edits'` — it carries no `edits` of its own and, like plain
+ * `'approve'`, activates the plan as staged, just with `PlanRecord.trustApprovedSteps` also set
+ * (see resolvePendingPlanApproval below and INV-36).
+ */
+export type PlanDecision = 'approve' | 'approve_trusted' | 'approve_with_edits' | 'decline';
+export interface PlanApprovalEdits {
+    cancelTaskIds?: string[];
+    editedTasks?: {
+        id: string;
+        description: string;
+    }[];
+}
+/**
+ * `PlanApprovalService.resolvePendingPlanApproval`'s result: either a terminal
+ * `AssistantTurnResult` (stale/missing staged plan, no decision supplied, or a failed
+ * approve/approve-with-edits — fail closed, `mode` left exactly as staged) or `{ fallThrough:
+ * true }`, meaning the plan record has already been updated (activated, or discarded) and
+ * `assistant.ts`'s `runTurn` should keep going with the *same originating message* through the
+ * ordinary pipeline below, per this phase's own scope: approve lets that pipeline pick up the
+ * now-`active` plan exactly the way a freshly template-matched plan already does today
+ * (`TurnInterpreter.resolveTasks` -> `loadActivePlan` -> `initialTasks`, regardless of what the
+ * message itself says, short of a cancel/abandon match) — no new execution-driving code needed,
+ * just reusing what already runs a plan's first task the moment it becomes `active`. Decline
+ * falls through the same way, but with no plan active at all.
+ */
+export type PlanApprovalOutcome = {
+    fallThrough: true;
+} | AssistantTurnResult;
+/**
+ * Owns plan mode's P2 mandatory whole-plan approval gate — mirrors ActionApprovalService's
+ * "resolved by ID, never re-derived" staging pattern (T4 of the file-tools plan), the same model
+ * AskClarificationService (Q2) already follows. Every drafted plan passes through here exactly
+ * once, regardless of risk (Section 5b-2: no risk-tiered skip) — `PlanDraftingService` calls
+ * `stageAndRespond` the moment a revision's `readyForApproval` is true, and
+ * `assistant.ts`'s `runTurn` calls `resolvePendingPlanApproval` whenever a turn carries a
+ * `planApprovalId`, before `planMode.active` is even checked (mirrors where `pendingActionId`/
+ * `pendingClarificationId` are checked).
+ */
+export declare class PlanApprovalService {
+    private readonly planService;
+    private readonly session;
+    private readonly onTrace;
+    constructor(planService: PlanService, session: AssistantSession, onTrace: ((event: TraceEvent) => void) | undefined);
+    /** Stages `plan` for approval and returns the `needs_plan_approval` result — the PlanDraftingService counterpart to AskClarificationService.stageAndRespond. */
+    stageAndRespond(sessionId: string, transcriptKey: string, plan: PlanRecord, userMessage: string): Promise<AssistantTurnResult>;
+    /**
+     * Resolves a staged plan by ID — validates it's still exactly the plan that was staged (a
+     * stale/unknown `planApprovalId` resolves to a no-op `ok`, same as
+     * AskClarificationService.resolvePendingClarification's own stale-ID handling), then applies
+     * the caller's decision. Fail-closed (Protected Invariants) on every failure path: no decision,
+     * or a throwing edit/activation step, leaves `mode: 'awaiting_approval'` untouched and returns a
+     * new `needs_plan_approval` result rather than silently advancing or discarding the plan.
+     */
+    resolvePendingPlanApproval(sessionId: string, planApprovalId: string, decision: PlanDecision | undefined, edits: PlanApprovalEdits | undefined): Promise<PlanApprovalOutcome>;
+}

package/dist/plan-builder.d.ts

@@ -0,0 +1,32 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { DecomposedTaskSpec } from './decomposition-classifier.js';
+import { PlanTemplate } from './plan-templates/index.js';
+export interface Plan {
+    templateName: string;
+    successCriteria: string;
+    tasks: DecomposedTaskSpec[];
+    /**
+     * Why this approach, not just what the success criteria are — optional for now since neither
+     * buildPlanFromTemplate's template-personalization call nor any other current producer of a
+     * Plan asks the LLM for one; plan-store.ts's createPlanRecord defaults it to '' when absent.
+     * A future from-scratch drafting path (plan mode's P3) is expected to populate it.
+     */
+    rationale?: string;
+}
+/**
+ * Spends one real LLM call personalizing `template`'s task skeleton to `message` —
+ * only called once classifyTurnIntent has already named a matchedPlanTemplate, so an
+ * ordinary turn never pays for this. Same "malformed/incomplete JSON is the expected
+ * failure mode, not the edge case" fallback classifyTurnIntent itself uses: any parse
+ * failure or a response with fewer than 2 usable tasks returns null, meaning "fall back to
+ * the caller's own ad hoc decomposition for this turn" rather than throwing.
+ *
+ * Each output task's `riskLevel` is attached from the matching skeleton task's own
+ * `risk_level` (curated by whoever wrote the template's JSON) by id, not asked of the LLM —
+ * the template already has this, more accurately than an LLM re-deriving it from a
+ * personalized one-line description would, and it costs zero extra output tokens. Falls back
+ * to 'LOW' only for the pathological case of a task id the LLM invented that doesn't match any
+ * skeleton task (the id/depends_on-must-match-skeleton instruction above means this should not
+ * happen in practice).
+ */
+export declare function buildPlanFromTemplate(llmClient: ILLMClient, message: string, template: PlanTemplate, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<Plan | null>;