@dv.nghiem/flowdeck 0.4.12 → 0.5.0

package/dist/services/lazy-rule-loader.d.ts

@@ -99,6 +99,8 @@ export declare function detectProjectLanguages(projectRoot: string): string[];
 export declare function buildSelectionDiagnostics(selection: RuleSelection, context: SelectionContext): string;
 /** Invalidate the discovery cache (call after rule files change, e.g. in tests). */
 export declare function invalidateRuleCache(): void;
+/** Alias exported for prompt-cache invalidation. */
+export declare function invalidateCache(): void;
 /** Return current cache entry count (for tests/telemetry). */
 export declare function getRuleCacheSize(): number;
 //# sourceMappingURL=lazy-rule-loader.d.ts.map

package/dist/services/lazy-rule-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lazy-rule-loader.d.ts","sourceRoot":"","sources":["../../src/services/lazy-rule-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAA;IACnB,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAA;IAClB;;;OAGG;IACH,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB;;;OAGG;IACH,SAAS,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAOD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyBzE;AAkCD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,CA0B9D;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,aAAa,CAiDf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,MAAM,EAAE,GAC1B,MAAM,EAAE,CAGV;AAID;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAiDpE;AAID;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAgBR;AAID,oFAAoF;AACpF,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}
+{"version":3,"file":"lazy-rule-loader.d.ts","sourceRoot":"","sources":["../../src/services/lazy-rule-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAA;IACnB,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAA;IAClB;;;OAGG;IACH,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB;;;OAGG;IACH,SAAS,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAOD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyBzE;AAkCD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,CA0B9D;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,aAAa,CAiDf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,MAAM,EAAE,GAC1B,MAAM,EAAE,CAGV;AAID;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAiDpE;AAID;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAgBR;AAID,oFAAoF;AACpF,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,oDAAoD;AACpD,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}

package/dist/services/prompt-cache.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Prompt Cache
+ *
+ * Caches assembled prompt fragments keyed by task description, workflow stage,
+ * and detected languages. Entries expire after a 5-minute TTL by default.
+ *
+ * Thread safety: operations are synchronous and run in the single-process event
+ * loop, so the internal Map is safe from races.
+ */
+export interface PromptCache {
+    /** Build a deterministic cache key from task + stage + languages. */
+    getKey(description: string, stage: string, languages: string[]): string;
+    /** Return a cached fragment if it is still fresh. */
+    get(key: string): string | undefined;
+    /** Store a fragment with an optional TTL (defaults to 5 minutes). */
+    set(key: string, fragment: string, ttlMs?: number): void;
+    /** Drop all cached fragments and invalidate downstream rule caches. */
+    invalidate(): void;
+}
+export declare const DEFAULT_PROMPT_CACHE_TTL_MS: number;
+/** Factory for creating a fresh prompt cache (mostly useful in tests). */
+export declare function createPromptCache(): PromptCache;
+/** Shared process-wide prompt cache used by the context ingress service. */
+export declare const sharedPromptCache: PromptCache;
+//# sourceMappingURL=prompt-cache.d.ts.map

package/dist/services/prompt-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-cache.d.ts","sourceRoot":"","sources":["../../src/services/prompt-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;IACvE,qDAAqD;IACrD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACpC,qEAAqE;IACrE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxD,uEAAuE;IACvE,UAAU,IAAI,IAAI,CAAA;CACnB;AAOD,eAAO,MAAM,2BAA2B,QAAgB,CAAA;AAmCxD,0EAA0E;AAC1E,wBAAgB,iBAAiB,IAAI,WAAW,CAE/C;AAED,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,EAAE,WAAmC,CAAA"}

package/dist/services/recovery-layer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Recovery Layer
+ *
+ * Detect stuck runs, explain blockages, recommend recovery actions,
+ * surface relevant failures from the failure-replay engine, and bound retries.
+ */
+import { type DeadlockSignal } from "./deadlock-detector";
+import { type FailureEntry } from "../tools/failure-replay";
+import type { RunContext, RecoveryAction } from "./harness-types";
+import type { TaskType } from "./quick-router";
+export interface RecoveryLayer {
+    /** Analyze recent spans and signals for stuck patterns. */
+    detectStuckRun(dir: string, runId: string): DeadlockSignal[];
+    /** Return true if the run has any auto-stop deadlock signal. */
+    isRunStuck(dir: string, runId: string): boolean;
+    /** Return a human-readable explanation of why the run is blocked. */
+    explainBlockage(ctx: RunContext): string;
+    /** Recommend the next recovery action: retry, fallback-agent, escalate, stop. */
+    recommendRecovery(ctx: RunContext, signals: DeadlockSignal[]): RecoveryAction;
+    /** Check whether a retry is still allowed for the current step. */
+    canRetry(runId: string): boolean;
+    /** Surface recent failures relevant to the current task. */
+    getRelevantFailures(dir: string, taskType: TaskType): FailureEntry[];
+}
+export declare function createRecoveryLayer(appLog?: (msg: string) => void): RecoveryLayer;
+//# sourceMappingURL=recovery-layer.d.ts.map

package/dist/services/recovery-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-layer.d.ts","sourceRoot":"","sources":["../../src/services/recovery-layer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAA;AAM5B,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAE9C,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,CAAA;IAC5D,gEAAgE;IAChE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;IAC/C,qEAAqE;IACrE,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAAA;IACxC,iFAAiF;IACjF,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,cAAc,CAAA;IAC7E,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;IAChC,4DAA4D;IAC5D,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,YAAY,EAAE,CAAA;CACrE;AAwCD,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,aAAa,CAoFjF"}

package/dist/services/run-trace.d.ts

@@ -1,4 +1,10 @@
+import type { DelegationBudgetSnapshot } from "./delegation-budget";
 export type RunStatus = "running" | "complete" | "failed" | "cancelled";
+export interface VerificationRecord {
+    kind: string;
+    evidence: string;
+    timestamp: string;
+}
 export interface RunTrace {
     run_id: string;
     session_id: string;
@@ -12,6 +18,8 @@ export interface RunTrace {
     risk_score: number;
     outcome?: string;
     error?: string;
+    budget_snapshot?: DelegationBudgetSnapshot;
+    verifications?: VerificationRecord[];
 }
 export declare function runsPath(dir: string): string;
 export declare function startTrace(dir: string, command: string, args: Record<string, unknown>, session_id?: string): RunTrace;
@@ -19,7 +27,16 @@ export declare function endTrace(dir: string, run_id: string, status: Exclude<Ru
 export declare function touchFile(dir: string, run_id: string, filePath: string): void;
 export declare function setRiskScore(dir: string, run_id: string, score: number): void;
 export declare function getTrace(dir: string, run_id: string): RunTrace | null;
+export declare function recordBudget(dir: string, run_id: string, snapshot: DelegationBudgetSnapshot): void;
 export declare function listTraces(dir: string, limit?: number): RunTrace[];
+/**
+ * Return the most recent running trace for a session, or undefined if none.
+ */
+export declare function findRunningTrace(dir: string, sessionID: string): RunTrace | undefined;
+/**
+ * Append a verification record to the run trace.
+ */
+export declare function recordVerification(dir: string, run_id: string, kind: string, evidence: string): void;
 export interface RunDiff {
     run_a: string;
     run_b: string;

package/dist/services/run-trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-trace.d.ts","sourceRoot":"","sources":["../../src/services/run-trace.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAA;AAEvE,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,SAAS,CAAA;IACjB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,SAAc,GACvB,QAAQ,CAiBV;AAqBD,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,EACrC,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAYN;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAS7E;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAM7E;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAErE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,QAAQ,EAAE,CAG9D;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,cAAc,EAAE,OAAO,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,OAAO,CAAA;CACzB;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAkB1F"}
+{"version":3,"file":"run-trace.d.ts","sourceRoot":"","sources":["../../src/services/run-trace.ts"],"names":[],"mappings":"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"}

package/dist/services/state-persistence.d.ts

@@ -0,0 +1,22 @@
+/**
+ * State Persistence Service
+ *
+ * Facade over run-trace, agent-trace-graph, and workflow-scorecard.
+ * Manages RunContext lifecycle and agent span tracking.
+ */
+import type { RunContext, AgentSpan, SpanStatus, SpanCloseOpts } from "./harness-types";
+export interface StatePersistenceService {
+    startRun(command: string, args: Record<string, unknown>, sessionID: string): RunContext;
+    endRun(ctx: RunContext, status: "complete" | "failed" | "cancelled", outcome?: string, error?: string, scorecardInput?: import("./workflow-scorecard").ScorecardInput): void;
+    openAgentSpan(ctx: RunContext, parentSpanId: string | undefined, agent: string, task: string, stage: string): AgentSpan;
+    closeAgentSpan(spanId: string, status: SpanStatus, opts?: SpanCloseOpts): void;
+    recordObservation(ctx: RunContext, type: string, content: string): void;
+    getRunContext(sessionID: string): RunContext | undefined;
+    updateRunContext(ctx: RunContext): void;
+}
+export interface StatePersistenceOptions {
+    directory: string;
+    appLog?: (msg: string) => void;
+}
+export declare function createStatePersistence(options: StatePersistenceOptions): StatePersistenceService;
+//# sourceMappingURL=state-persistence.d.ts.map

package/dist/services/state-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-persistence.d.ts","sourceRoot":"","sources":["../../src/services/state-persistence.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAKvF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,CAAA;IACvF,MAAM,CACJ,GAAG,EAAE,UAAU,EACf,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,WAAW,EAC3C,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,OAAO,sBAAsB,EAAE,cAAc,GAC7D,IAAI,CAAA;IACP,aAAa,CACX,GAAG,EAAE,UAAU,EACf,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,SAAS,CAAA;IACZ,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;IAC9E,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACvE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;IACxD,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAA;CACxC;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/B;AAID,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CA4GhG"}

package/dist/services/supervisor-binding.d.ts

@@ -14,6 +14,7 @@
  *   - It returns a structured decision
  *   - It NEVER creates or modifies commands or workflows
  */
+import type { PolicyDecision, PolicyInput } from "./harness-types";
 /**
  * The canonical set of registered FlowDeck commands.
  * This list is derived from src/commands/*.md at build time and must NOT
@@ -113,6 +114,14 @@ export declare function isRegisteredTarget(name: string): {
  * the requested target is not registered.
  */
 export declare function runSupervisorReview(directory: string, targetName: string, ctx?: SupervisorContext, clarificationQuestion?: string): SupervisorDecision;
+/**
+ * Review a tool call target through the supervisor lens.
+ *
+ * Returns a PolicyDecision so the harness can treat supervisor review like
+ * any other policy layer. `revise` and `escalate` are surfaced as `ask`
+ * verdicts; `block` is a `deny`; `approve` is an `allow`.
+ */
+export declare function reviewToolCall(directory: string, input: PolicyInput): PolicyDecision;
 /**
  * Shorthand: should execution proceed given a decision and the current config mode?
  * In "advisory" mode, only "block" with a missing-existence check is hard-stopped.

package/dist/services/supervisor-binding.d.ts.map

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

package/dist/services/token-metrics.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Token Metrics
+ *
+ * Tracks per-run token usage from message.updated-style usage payloads and
+ * estimates cost. Used by the context ingress layer for real token budgets
+ * and by the context window monitor for usage warnings.
+ */
+export interface TokenUsageInfo {
+    input?: number;
+    output?: number;
+    reasoning?: number;
+    cache?: {
+        read?: number;
+        write?: number;
+    };
+}
+export interface RunUsageSnapshot {
+    runId: string;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    messageCount: number;
+}
+export declare const DEFAULT_INPUT_PRICE_PER_1M_TOKENS = 3;
+export declare const DEFAULT_OUTPUT_PRICE_PER_1M_TOKENS = 15;
+/** Record token usage from a single message.updated-like event. */
+export declare function recordMessageUsage(runId: string, usage: TokenUsageInfo): void;
+/** Return the accumulated usage for a run, or zeros if none recorded. */
+export declare function getRunUsage(runId: string): RunUsageSnapshot;
+/** Estimate cumulative cost in USD for a run. */
+export declare function estimateCostUSD(runId: string): number;
+/** Check whether a run's estimated cost exceeds a maximum budget. */
+export declare function isOverBudget(runId: string, maxCost: number): boolean;
+/** Clear all recorded usage (intended for tests). */
+export declare function resetTokenMetrics(): void;
+//# sourceMappingURL=token-metrics.d.ts.map

package/dist/services/token-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-metrics.d.ts","sourceRoot":"","sources":["../../src/services/token-metrics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAA;CACF;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe,EAAE,MAAM,CAAA;IACvB,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;IACxB,YAAY,EAAE,MAAM,CAAA;CACrB;AAID,eAAO,MAAM,iCAAiC,IAAI,CAAA;AAClD,eAAO,MAAM,kCAAkC,KAAK,CAAA;AAqCpD,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAW7E;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAiB3D;AAED,iDAAiD;AACjD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOrD;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/services/verification-layer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Verification Layer
+ *
+ * Thin wrapper over command-validator, completion-validator, and
+ * agent-validator. Called by the harness controller after model outputs
+ * and before marking phases complete.
+ */
+import { type FullAuditResult } from "./command-validator";
+import { type CompletionReadiness } from "../lib/completion-validator";
+import { type ValidationResult } from "./agent-validator";
+import type { RunContext } from "./harness-types";
+import type { PlanningState } from "../tools/planning-state-lib";
+export interface VerificationLayer {
+    /** Validate that a command reference in model output is registered. */
+    validateCommandRefs(text: string): FullAuditResult;
+    /** Validate completion readiness before allowing /fd-done. */
+    validateCompletion(state: PlanningState): CompletionReadiness;
+    /** Validate that an agent's output conforms to its contract fields. */
+    validateAgentOutput(agent: string, output: Record<string, unknown>): ValidationResult;
+    /** Record a verified outcome (test passed, review approved, etc.) to the run trace. */
+    recordVerification(ctx: RunContext, kind: string, evidence: string): void;
+}
+export declare function createVerificationLayer(directory: string): VerificationLayer;
+//# sourceMappingURL=verification-layer.d.ts.map

package/dist/services/verification-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-layer.d.ts","sourceRoot":"","sources":["../../src/services/verification-layer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACzE,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAE9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAEhE,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAA;IAClD,8DAA8D;IAC9D,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,mBAAmB,CAAA;IAC7D,uEAAuE;IACvE,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,CAAA;IACrF,uFAAuF;IACvF,kBAAkB,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1E;AAED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,CAkB5E"}

package/dist/services/workflow-scorecard.d.ts

@@ -4,6 +4,7 @@
  * Scores across 10 dimensions; stored in .codebase/SCORECARDS.jsonl for trend analysis.
  */
 import type { RunTrace } from "./run-trace";
+import type { AuditEntry } from "./harness-types";
 export interface ScorecardDimensions {
     /** Agents followed phase order and didn't skip required stages */
     stageCompliance: number;
@@ -31,6 +32,8 @@ export interface ScorecardDimensions {
      * Defaults to 1.0 when the supervisor is disabled or no reviews occurred.
      */
     supervisorCompliance: number;
+    /** Overall governance adherence derived from audit entries */
+    governanceCompliance: number;
 }
 export interface WorkflowScorecard {
     scorecard_id: string;
@@ -75,6 +78,8 @@ export interface ScorecardInput {
      * Computed automatically from telemetry when omitted.
      */
     supervisor_hard_stops?: number;
+    /** Audit entries for this run, used to score governance compliance. */
+    audit_entries?: AuditEntry[];
 }
 export declare function scorecardsPath(dir: string): string;
 /**

package/dist/services/workflow-scorecard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-scorecard.d.ts","sourceRoot":"","sources":["../../src/services/workflow-scorecard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAI3C,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,eAAe,EAAE,MAAM,CAAA;IACvB,uDAAuD;IACvD,qBAAqB,EAAE,MAAM,CAAA;IAC7B,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,kBAAkB,EAAE,MAAM,CAAA;IAC1B,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAA;IACvB,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAA;IACxB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAA;IACvB,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAA;IACtB,mCAAmC;IACnC,kBAAkB,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,oBAAoB,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,iBAAiB,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAA;IAClE,UAAU,EAAE,mBAAmB,CAAA;IAC/B,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAA;IACrB,iBAAiB,EAAE,MAAM,CAAA;IACzB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,cAAc,EAAE,MAAM,CAAA;IACtB,gBAAgB,EAAE,MAAM,CAAA;IACxB,kDAAkD;IAClD,kBAAkB,EAAE,MAAM,CAAA;IAC1B,4DAA4D;IAC5D,qBAAqB,EAAE,MAAM,CAAA;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,4CAA4C;IAC5C,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,iDAAiD;IACjD,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,4CAA4C;IAC5C,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B;AAgBD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,QAAQ,EACf,KAAK,GAAE,cAAmB,GACzB,iBAAiB,CAyEnB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,iBAAiB,EAAE,CAS3E;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAEvF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,iBAAiB,EAAE,CAIhG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIhF"}
+{"version":3,"file":"workflow-scorecard.d.ts","sourceRoot":"","sources":["../../src/services/workflow-scorecard.ts"],"names":[],"mappings":"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"}

package/dist/tools/decision-trace.d.ts

@@ -11,6 +11,10 @@ export interface DecisionEntry {
     alternatives_considered: string[];
     risk_level: "low" | "medium" | "high";
     agent?: string;
+    /** Policy reason that authorized or denied the change, when available. */
+    policy_reason?: string;
+    /** Audit entry id correlating this decision to the audit log. */
+    audit_entry_id?: string;
 }
 export declare const decisionTraceTool: ToolDefinition;
 //# sourceMappingURL=decision-trace.d.ts.map

package/dist/tools/decision-trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decision-trace.d.ts","sourceRoot":"","sources":["../../src/tools/decision-trace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAO/D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAA;IACtD,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,uBAAuB,EAAE,MAAM,EAAE,CAAA;IACjC,UAAU,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAgBD,eAAO,MAAM,iBAAiB,EAAE,cA4D9B,CAAA"}
+{"version":3,"file":"decision-trace.d.ts","sourceRoot":"","sources":["../../src/tools/decision-trace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAO/D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAA;IACtD,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,uBAAuB,EAAE,MAAM,EAAE,CAAA;IACjC,UAAU,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAgBD,eAAO,MAAM,iBAAiB,EAAE,cA4D9B,CAAA"}

package/dist/tools/delegate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Delegate Tool
+ *
+ * Runtime delegation primitive for the orchestrator. Replaces raw @agent
+ * references with an explicit tool call that:
+ *  - enforces delegation-budget.maxDepth
+ *  - tracks parent-child spans in the agent trace graph
+ *  - returns a structured DelegateResult
+ */
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { OpencodeClient } from "@opencode-ai/sdk";
+import type { StatePersistenceService } from "../services/state-persistence";
+import type { DelegateResult, DelegateToolArgs } from "../services/harness-types";
+export type { DelegateResult, DelegateToolArgs };
+export declare function createDelegateTool(client: OpencodeClient, statePersistence: StatePersistenceService): ToolDefinition;
+//# sourceMappingURL=delegate.d.ts.map

package/dist/tools/delegate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../../src/tools/delegate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAGtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAA;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAc,MAAM,2BAA2B,CAAA;AAG7F,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;AAShD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,cAAc,EACtB,gBAAgB,EAAE,uBAAuB,GACxC,cAAc,CAqGhB"}

package/dist/tools/failure-replay.d.ts

@@ -15,5 +15,13 @@ export interface FailureStore {
     last_updated: string;
     entries: FailureEntry[];
 }
+export interface FailureFilter {
+    type?: FailureEntry["type"];
+    path_prefix?: string;
+    tag?: string;
+    limit?: number;
+}
+export declare function queryFailures(directory: string, filter?: FailureFilter): FailureEntry[];
+export declare function listFailures(directory: string, limit?: number): FailureEntry[];
 export declare const failureReplayTool: ToolDefinition;
 //# sourceMappingURL=failure-replay.d.ts.map

package/dist/tools/failure-replay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"failure-replay.d.ts","sourceRoot":"","sources":["../../src/tools/failure-replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAO/D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,YAAY,GAAG,SAAS,GAAG,eAAe,CAAA;IAC1F,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,YAAY,EAAE,CAAA;CACxB;AAuBD,eAAO,MAAM,iBAAiB,EAAE,cA0E9B,CAAA"}
+{"version":3,"file":"failure-replay.d.ts","sourceRoot":"","sources":["../../src/tools/failure-replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAO/D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,YAAY,GAAG,SAAS,GAAG,eAAe,CAAA;IAC1F,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,YAAY,EAAE,CAAA;CACxB;AAuBD,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,CAAA;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,YAAY,EAAE,CAW3F;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,YAAY,EAAE,CAK1E;AAED,eAAO,MAAM,iBAAiB,EAAE,cA0E9B,CAAA"}

package/dist/tools/policy-engine.d.ts

@@ -15,5 +15,6 @@ export interface PolicyStore {
     last_updated: string;
     policies: Policy[];
 }
+export declare function readStore(directory: string): PolicyStore;
 export declare const policyEngineTool: ToolDefinition;
 //# sourceMappingURL=policy-engine.d.ts.map

package/dist/tools/policy-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy-engine.d.ts","sourceRoot":"","sources":["../../src/tools/policy-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAO/D,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC5B,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAuBD,eAAO,MAAM,gBAAgB,EAAE,cAyE7B,CAAA"}
+{"version":3,"file":"policy-engine.d.ts","sourceRoot":"","sources":["../../src/tools/policy-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAO/D,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC5B,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAMD,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAQxD;AASD,eAAO,MAAM,gBAAgB,EAAE,cAyE7B,CAAA"}

package/docs/concepts/HARNESS_ARCHITECTURE.md

@@ -0,0 +1,241 @@
+# FlowDeck Target Harness Architecture
+
+**Status**: Proposed  
+**Scope**: Transform FlowDeck from a prompt-heavy plugin into a real agent-harness engineering runtime while staying OpenCode-native.
+
+## 1. Core idea
+
+Today FlowDeck registers agents, rules, skills, commands, hooks and tools, but most critical behavior lives in prompts (orchestrator prompt, command markdown). Several runtime services exist as code and tests but are not wired into the plugin lifecycle. The target architecture moves three things into runtime enforcement:
+
+1. **Delegation is explicit.** The orchestrator no longer "asks" the model to route; it calls a `delegate` tool that the harness executes, tracks, and budgets.
+2. **Policy is executable.** Agent contracts, supervisor review, approval gates, and loop/deadlock detection run in hooks/services, not only in prompt text.
+3. **State is first-class.** Workflow state, run traces, agent spans, approvals, and observations are persisted, queryable, and used for recovery, review, and audit.
+
+The model is still the reasoner, but the harness owns execution, state, and governance.
+
+## 2. Design principles
+
+- **Correctness first**: use existing working services before inventing new ones.
+- **OpenCode-native**: keep tools, permissions allow/deny/ask, agents, skills, hooks, and config.
+- **Prompts describe, runtime enforces**: contracts, budgets, gates, and routing are checked in code.
+- **Minimum surface area**: only expose what callers (agents/commands) need.
+- **Testable layers**: each layer has narrow interfaces and can be exercised without the full OpenCode runtime.
+
+## 3. High-level component diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          OpenCode host                                  │
+│  (model, session, native tools, permissions, agents, commands, skills)  │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         FlowDeck plugin (src/index.ts)                  │
+│  registers agents, tools, hooks, MCPs, commands, skills, rules          │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+        ┌───────────────────────────┼───────────────────────────┐
+        ▼                           ▼                           ▼
+┌───────────────┐          ┌───────────────┐          ┌───────────────┐
+│ ContextIngress│          │ ActionMediator│          │ExecutionSubstrate
+│  Service      │          │   Service     │          │   Service     │
+└───────┬───────┘          └───────┬───────┘          └───────┬───────┘
+        │                          │                          │
+        ▼                          ▼                          ▼
+┌───────────────┐          ┌───────────────┐          ┌───────────────┐
+│StatePersistence│         │Verification&  │          │Recovery&      │
+│   Service     │          │   Review      │          │   Debugging   │
+└───────┬───────┘          └───────┬───────┘          └───────┬───────┘
+        │                          │                          │
+        └──────────────────────────┼──────────────────────────┘
+                                   ▼
+                    ┌─────────────────────────────┐
+                    │  Delegation & Coordination  │
+                    │   (orchestrator + router)   │
+                    └─────────────────────────────┘
+                                   │
+                                   ▼
+                    ┌─────────────────────────────┐
+                    │   Governance & Audit        │
+                    │ (contracts, approvals, logs)│
+                    └─────────────────────────────┘
+```
+
+## 4. End-to-end data flow
+
+A typical user request (`/fd-quick "add auth middleware"`) flows through the harness:
+
+1. **Command entry** — OpenCode fires `command.execute.before`/`after`. The harness starts a `RunTrace` (run_id).
+2. **Context ingress** — `ContextIngressService` assembles `STATE.md`, `PLAN.md`, `.codebase/` docs, recent events, relevant skills/rules, and a token-budget snapshot. It short-circuits to the trivial-chat path if the request is a simple question.
+3. **Routing** — `quick-router` + `workflow-router` classify the task and produce a `WorkflowRoute` (workflow class + stage sequence). `model-router` provides complexity/eligible-agent hints.
+4. **Delegation** — The orchestrator calls the `delegate` tool. `ActionMediator` validates the target agent against `agent-contract-registry`, runs `agent-validator`, checks `supervisor-binding`, and enforces the delegation budget.
+5. **Execution** — `ExecutionSubstrate` opens an `AgentSpan` (agent-trace-graph), tracks the child session, applies tool lifecycle hooks, and records cost/time.
+6. **Tool mediation** — On every `tool.execute.before`, `ActionMediator` normalizes args, classifies risk, runs approval gates (`approval-manager`), arch constraints, phase gates, loop detection, and orchestrator guard.
+7. **State persistence** — Each meaningful change writes to `.planning/STATE.md`, `.codebase/RUNS.jsonl`, `.codebase/AGENT_SPANS.jsonl`, `.opencode/flowdeck-events.jsonl`, or `.codebase/APPROVALS.json`.
+8. **Verification** — At stage boundaries `VerificationService` checks tests, coverage, review verdict, and design approval before allowing the next stage.
+9. **Recovery** — If a span fails or a deadlock/loop signal fires, `RecoveryService` classifies the failure, bounds retries, and either re-routes, escalates, or stops.
+10. **Audit** — On run end, `WorkflowScorecard` is generated and `AGENT_PERF.json` is updated.
+
+## 5. Key interface contracts
+
+These interfaces are the contracts between layers. Implementations may be added incrementally.
+
+### 5.1 Context ingress
+
+```typescript
+// src/services/context-ingress.ts
+export interface AssembledContext {
+  runId: string;
+  sessionId: string;
+  projectRoot: string;
+  state: PlanningState;
+  route: WorkflowRoute | null;
+  relevantRules: string[];
+  relevantSkills: string[];
+  recentEvents: ToolEvent[];
+  observations: Observation[];
+  tokenBudget: TokenBudgetSnapshot;
+  isTrivialChat: boolean;
+}
+
+export interface ContextIngressService {
+  assemble(input: { command: string; args: string; sessionId: string }): Promise<AssembledContext>;
+  refreshRunId(ctx: AssembledContext): AssembledContext;
+  snapshotBudget(ctx: AssembledContext): TokenBudgetSnapshot;
+}
+```
+
+### 5.2 Action mediator
+
+```typescript
+// src/services/action-mediator.ts
+export interface ActionRequest {
+  toolName: string;
+  args: Record<string, unknown>;
+  agentName?: string;
+  runId: string;
+  sessionId: string;
+}
+
+export interface ActionDecision {
+  action: "allow" | "block" | "ask" | "escalate";
+  reason: string;
+  riskScore: number;
+  requiredApprovalId?: string;
+}
+
+export interface ActionMediatorService {
+  check(request: ActionRequest): ActionDecision;
+  recordOutcome(request: ActionRequest, decision: ActionDecision, output: unknown): void;
+}
+```
+
+### 5.3 Delegation
+
+```typescript
+// src/tools/delegate.ts
+export interface DelegateInput {
+  target: "agent" | "command";
+  name: string;                 // e.g. "backend-coder" or "fd-plan"
+  taskDescription: string;
+  contextSummary?: string;
+  mode?: "quick" | "standard" | "explore" | "verify-heavy";
+  parentSpanId?: string;
+}
+
+export interface DelegateResult {
+  spanId: string;
+  childSessionId?: string;
+  status: "running" | "blocked" | "escalated";
+  reason?: string;
+}
+```
+
+### 5.4 Run pipeline
+
+```typescript
+// src/tools/run-pipeline.ts
+export interface RunPipelineInput {
+  workflowClass: WorkflowClass;
+  stages?: string[];            // optional override
+  taskDescription: string;
+  confirm?: boolean;
+}
+
+export interface RunPipelineResult {
+  runId: string;
+  completedStages: string[];
+  currentStage: string | null;
+  blocked: boolean;
+  blockedReason?: string;
+}
+```
+
+### 5.5 Delegation budget
+
+```typescript
+// src/services/delegation-budget.ts
+export interface DelegationBudget {
+  runId: string;
+  maxToolCalls: number;
+  maxDepth: number;
+  maxSameStepRetries: number;
+  spentToolCalls: number;
+  currentDepth: number;
+}
+
+export interface DelegationBudgetService {
+  init(runId: string, config?: Partial<DelegationBudget>): DelegationBudget;
+  checkSpend(runId: string, toolName: string): { ok: boolean; remaining: number };
+  recordDelegation(parentRunId: string, childRunId: string): boolean;
+}
+```
+
+## 6. State files
+
+| File | Owner | Purpose | Lifecycle |
+|------|-------|---------|-----------|
+| `.planning/STATE.md` | `planning-state` tool | Current phase, plan confirmation, design gates | Long-lived, updated per phase |
+| `.planning/PLAN.md` | `planning-state` tool | Numbered plan steps | Long-lived, created per feature |
+| `.codebase/RUNS.jsonl` | `run-trace` service | Command-level run history | Append-only |
+| `.codebase/AGENT_SPANS.jsonl` | `agent-trace-graph` service | Causal agent delegation spans | Append-only |
+| `.codebase/SCORECARDS.jsonl` | `workflow-scorecard` service | 10-dimension run quality scores | Append-only |
+| `.codebase/DEADLOCK_SIGNALS.jsonl` | `deadlock-detector` service | Detected loop/deadlock signals | Append-only |
+| `.codebase/APPROVALS.json` | `approval-manager` service | Pending/approved sensitive operations | Mutable |
+| `.codebase/AGENT_PERF.json` | `agent-performance` service | Per-agent/model/task success stats | Mutable |
+| `.codebase/WORKFLOW_ROUTING.jsonl` | `workflow-router` service | Routing decisions and escalations | Append-only |
+| `.opencode/flowdeck-events.jsonl` | `event-logger` service | Raw tool/session events | Append-only, rotated |
+
+## 7. Failure modes and recovery
+
+| Failure | Detection | Recovery |
+|---------|-----------|----------|
+| Same tool repeated with same result | `LoopDetector` in `tool.execute.before` | Block + escalation message |
+| Agent bounce / circular delegation | `deadlock-detector` over `AGENT_SPANS.jsonl` | Log signal, auto-stop if configured |
+| Budget exhausted | `DelegationBudgetService` | Warn / stop / escalate based on `governance.costBudget.onExhaustion` |
+| Approval missing | `approval-hook` + `ActionMediator` | Block with `APPROVAL_REQUIRED` and approval id |
+| Contract violation | `agent-validator` | Advisory warning or strict block |
+| Child session error | `event` hook `session.error` | Close span as `failed`, surface to parent |
+| Tool persistence failure | `event-logger` health flag | Loop detection falls back to in-memory, logs warning |
+| Unregistered target | `supervisor-binding` + `command-validator` | Block before execution |
+
+## 8. Security considerations
+
+- Secrets never enter state files; event args are sanitized by `sanitizeArgs`.
+- Sensitive paths require explicit approval stored in `.codebase/APPROVALS.json` with TTL.
+- Orchestrator cannot use write/edit/bash tools; `OrchestratorGuard` throws.
+- Arch constraints in `.codebase/CONSTRAINTS.md` block edits to forbidden paths.
+- Phase gates block implementation during discuss/plan phases.
+- Tool guard blocks dangerous bash/read/write patterns when enabled.
+
+## 9. Migration path
+
+The harness is built incrementally. Each layer can be merged independently:
+
+1. Wire existing unwired services into `src/index.ts` (agent validator, trace graph, run trace, scorecard, deadlock detector, delegation budget). Existing behavior remains opt-in or advisory.
+2. Add `delegate` and `run-pipeline` tools behind feature flags; keep markdown commands as fallback.
+3. Replace prompt-based routing directives with tool calls once delegation is stable.
+4. Promote governance from advisory to strict via `flowdeck.json`.
+
+No existing public API is broken in step 1.