@voybio/ace-swarm 2.4.3 → 2.4.6

package/dist/store/gate-contract-migration.js

@@ -0,0 +1,413 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const PACKAGE_GATE_CONTRACT_VERSION = 2;
+export const PACKAGE_GATE_CONTRACT_VERSION_KEY = "meta/package_gate_contract_version";
+const LEGACY_GATE_MIGRATIONS = [
+    {
+        fileName: "gate-autonomy.json",
+        legacyContent: JSON.stringify({
+            id: "gate-autonomy",
+            type: "artifact_scan",
+            invariant: "Every execution cycle records objective, strategy, evidence, and next state",
+            command: "",
+            evidence_requirement: "STATUS + EVIDENCE_LOG + HANDOFF pointers",
+        }, null, 2),
+        currentAssetRelativePath: "agent-state/MODULES/gates/gate-autonomy.json",
+    },
+    {
+        fileName: "gate-completeness.json",
+        legacyContent: JSON.stringify({
+            id: "gate-completeness",
+            type: "artifact_scan",
+            invariant: "All required artifacts exist and are non-empty",
+            command: "",
+            evidence_requirement: "File presence and section completeness evidence",
+        }, null, 2),
+        currentAssetRelativePath: "agent-state/MODULES/gates/gate-completeness.json",
+    },
+    {
+        fileName: "gate-operability.json",
+        legacyContent: JSON.stringify({
+            id: "gate-operability",
+            type: "artifact_scan",
+            invariant: "Runbooks, ownership, and incident routing are defined for release",
+            command: "",
+            evidence_requirement: "COMMUNICATION_CHANNELS.md + observability/release artifacts",
+        }, null, 2),
+        currentAssetRelativePath: "agent-state/MODULES/gates/gate-operability.json",
+    },
+    {
+        fileName: "gate-security.json",
+        legacyContent: JSON.stringify({
+            id: "gate-security",
+            type: "manual_review",
+            invariant: "No unmitigated high-severity security or policy risks",
+            command: "",
+            evidence_requirement: "SECURITY_REPORT.md with explicit mitigations or accepted residual risk",
+        }, null, 2),
+        currentAssetRelativePath: "agent-state/MODULES/gates/gate-security.json",
+    },
+    {
+        fileName: "gate-correctness.json",
+        legacyContent: JSON.stringify({
+            id: "gate-correctness",
+            type: "executable",
+            invariant: "All required tests pass",
+            command: "if [ -f ace-mcp-server/package.json ]; then cd ace-mcp-server && npm test --silent; elif [ -f package.json ]; then npm test --silent; else echo 'package.json not found for gate-correctness' && exit 1; fi",
+            evidence_requirement: "Command output snippet with exit code 0",
+        }, null, 2),
+        remove: true,
+    },
+    {
+        fileName: "gate-evaluation.json",
+        legacyContent: JSON.stringify({
+            id: "gate-evaluation",
+            type: "executable",
+            invariant: "Core autonomy benchmark suites meet defined pass thresholds",
+            command: "bash scripts/ace/eval-harness.sh",
+            evidence_requirement: "EVAL_REPORT.md + command output",
+        }, null, 2),
+        remove: true,
+    },
+    {
+        fileName: "gate-typescript-public-surface.json",
+        legacyContent: JSON.stringify({
+            id: "gate-typescript-public-surface",
+            type: "executable",
+            invariant: "Exported MCP tools, resources, prompts, and public status events stay registered, described, schema-backed where required, and covered by the audit gate",
+            command: "node --input-type=module -e \"import('./dist/public-surface.js').then(async (m) => { const result = await m.auditPublicSurface({ write_artifact: false }); if (!result.ok) { console.error(result.failures.join('\\n')); process.exit(1); } console.log(JSON.stringify(result.summary)); })\"",
+            evidence_requirement: "PUBLIC_SURFACE_REPORT.md + passing public-surface audit",
+        }, null, 2),
+        remove: true,
+    },
+];
+const LEGACY_STATIC_ASSET_MIGRATIONS = [
+    {
+        key: "knowledge/agent-state/TEAL_CONFIG.md",
+        legacyContent: `# TEAL_CONFIG.md
+
+\`\`\`yaml
+teal_version: "1.1"
+timestamp: "2026-03-03T20:45:00Z"
+
+modules:
+  skeptic:
+    version: "1.0.0"
+    interface: "QUALITY_GATES.md"
+    sidecar: true
+
+  ops:
+    version: "1.0.0"
+    outputs: ["STATUS.md", "HANDOFF.json"]
+
+  astgrep:
+    version: "1.0.0"
+    inputs: ["TASK.md", "SCOPE.md", "AST_GREP_COMMANDS.md"]
+    outputs: ["AST_GREP_INDEX.md", "AST_GREP_INDEX.json"]
+
+  research:
+    version: "1.0.0"
+    inputs: ["TASK.md"]
+    outputs: ["EVIDENCE_LOG.md"]
+
+  spec:
+    version: "1.0.0"
+    depends_on: ["research", "skeptic"]
+    outputs: ["SPEC_CONTRACT.json", "INTERFACE_REGISTRY.md"]
+
+  build:
+    version: "1.0.0"
+    depends_on: ["spec"]
+    parallelizable: true
+
+  qa:
+    version: "1.0.0"
+    depends_on: ["build"]
+    gates: ["gate-completeness", "gate-correctness", "gate-autonomy"]
+
+  docs:
+    version: "1.0.0"
+    depends_on: ["build", "qa"]
+
+  memory:
+    version: "1.0.0"
+    sidecar: true
+    depends_on: ["ops"]
+    outputs: ["MEMORY_INDEX.md"]
+
+  security:
+    version: "1.0.0"
+    sidecar: true
+    depends_on: ["skeptic", "spec", "build"]
+    gates: ["gate-security"]
+
+  observability:
+    version: "1.0.0"
+    sidecar: true
+    depends_on: ["ops", "qa"]
+    outputs: ["OBSERVABILITY_REPORT.md"]
+
+  eval:
+    version: "1.0.0"
+    depends_on: ["qa"]
+    gates: ["gate-evaluation"]
+
+  release:
+    version: "1.0.0"
+    depends_on: ["security", "observability", "eval"]
+    gates: ["gate-operability"]
+
+pipelines:
+  standard:
+    - astgrep -> research -> spec -> build -> qa -> docs
+    - skeptic (sidecar)
+
+  high_certainty:
+    - astgrep -> spec -> build -> qa
+    - security (sidecar)
+    - eval -> release
+
+  high_ambiguity:
+    - astgrep -> research -> spec -> build
+    - skeptic (continuous)
+    - memory (continuous)
+    - ops (orchestration)
+
+  production_promotion:
+    - qa -> security -> eval -> observability -> release
+
+gates:
+  gate-completeness:
+    module: qa
+    inputs: ["SPEC_CONTRACT.json", "artifact_set"]
+
+  gate-correctness:
+    module: qa
+    inputs: ["test_results", "EVIDENCE_LOG.md"]
+
+  gate-autonomy:
+    module: skeptic
+    inputs: ["STATUS.md", "HANDOFF.json", "EVIDENCE_LOG.md"]
+
+  gate-security:
+    module: security
+    inputs: ["RISKS.md", "SECURITY_REPORT.md"]
+
+  gate-evaluation:
+    module: eval
+    inputs: ["EVAL_REPORT.md"]
+
+  gate-operability:
+    module: release
+    inputs: ["OBSERVABILITY_REPORT.md", "RELEASE_DECISION.md"]
+\`\`\`
+`,
+        currentAssetRelativePath: "agent-state/TEAL_CONFIG.md",
+    },
+    {
+        key: "knowledge/agent-state/MODULES/registry.json",
+        legacyContent: JSON.stringify({
+            roles: [
+                "capability-astgrep",
+                "capability-skeptic",
+                "capability-ops",
+                "capability-research",
+                "capability-spec",
+                "capability-build",
+                "capability-qa",
+                "capability-docs",
+                "capability-memory",
+                "capability-security",
+                "capability-observability",
+                "capability-eval",
+                "capability-release",
+                "capability-safety",
+                "capability-framework",
+                "capability-git",
+            ],
+            gates: [
+                "gate-completeness",
+                "gate-correctness",
+                "gate-autonomy",
+                "gate-security",
+                "gate-operability",
+                "gate-evaluation",
+                "gate-typescript-public-surface",
+            ],
+            schemas: [
+                "STATUS_EVENT.schema.json",
+                "HANDOFF.schema.json",
+                "ARTIFACT_MANIFEST.schema.json",
+                "ACE_RUNTIME_PROFILE.schema.json",
+                "WORKSPACE_SESSION_REGISTRY.schema.json",
+                "RUNTIME_TOOL_SPEC_REGISTRY.schema.json",
+                "RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+                "TRACKER_SNAPSHOT.schema.json",
+                "VERICIFY_BRIDGE_SNAPSHOT.schema.json",
+                "VERICIFY_PROCESS_POST_LOG.schema.json",
+            ],
+        }, null, 2),
+        currentAssetRelativePath: "agent-state/MODULES/registry.json",
+    },
+    {
+        key: "knowledge/agent-state/QUALITY_GATES.md",
+        legacyContent: `# QUALITY GATES
+
+## gate-completeness
+
+- Invariant: required artifacts exist and are non-empty.
+- Pass condition: all required files are present with required sections.
+- Fail condition: any missing required artifact or empty required section.
+- Evidence: file list + section checks in \`EVIDENCE_LOG.md\`.
+
+## gate-correctness
+
+- Invariant: behavior satisfies spec acceptance criteria.
+- Pass condition: mapped tests pass and no unresolved critical failures.
+- Fail condition: failing mapped test, unresolved regression, or invalid provenance.
+- Evidence: test output and verification report pointers.
+`,
+        currentAssetRelativePath: "agent-state/QUALITY_GATES.md",
+    },
+    {
+        key: "knowledge/agent-state/INTERFACE_REGISTRY.md",
+        legacyContent: `# INTERFACE_REGISTRY
+
+## Runtime Executor Session Contract
+
+- \`runtime-executor-sessions.json\` is the authoritative session registry for unattended runtime executor workspaces.
+- It must validate against \`MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json\`.
+- Every session entry must expose \`session_id\`, \`workspace_path\`, \`root_path\`, \`status\`, \`source\`, timestamps, optional hook details, and any \`metadata\` required for routing/debugging.
+
+## Runtime Tool Spec Contract
+
+- \`runtime-tool-specs.json\` is the authoritative registry for external runtime tool declarations.
+- It must validate against \`MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json\`.
+- Each tool entry must include deterministic command metadata and explicitly declare environment inputs under \`env_keys\`.
+
+## Workspace Session Registry Contract
+
+- \`runtime-workspaces.json\` is the authoritative registry for active ACE workspace sessions.
+- It must validate against \`MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json\`.
+- Entries may optionally include hook health summaries and per-hook status under \`hooks\`.
+
+## Tracker Snapshot Contract
+
+- \`tracker-snapshot.json\` is the normalized cache of task/comment data mirrored from provider trackers.
+- It must validate against \`MODULES/schemas/TRACKER_SNAPSHOT.schema.json\`.
+- Scheduler and future executor consumers must use normalized item/comment fields only; provider-specific detail belongs under \`metadata\`.
+
+## Vericify Sidecar Contract
+
+- \`vericify/ace-bridge.json\` is an optional sidecar bridge snapshot for Vericify-style read-model consumers.
+- It must validate against \`MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json\`.
+- \`vericify/process-posts.json\` is an optional structured process-post log and must validate against \`MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json\`.
+- Vericify remains optional; ACE must not require the Vericify package to read or write these artifacts.
+
+## Public Surface Gate
+
+- \`audit_public_surface\` is the canonical TypeScript public-surface gate for MCP tools, resources, prompts, and registered event names.
+- \`PUBLIC_SURFACE_REPORT.md\` is the durable audit artifact written by that gate.
+- \`MODULES/gates/gate-typescript-public-surface.json\` is the executable gate manifest for CI or operator use.
+
+## Provenance Contract
+
+- \`ARTIFACT_MANIFEST.json\` is mandatory and must be schema-valid.
+- Each artifact entry must include \`artifact_id\`, \`artifact_path\`, \`producer_module\`, \`spec_version\`, \`req_ids\`, \`checksum\`, \`confidence_level\`, \`evidence_ref\`, and \`timestamp\`.
+- \`PROVENANCE_LOG.md\` must mirror manifest entries with append-only evidence-linked records.
+
+## Versioning Rules
+
+- additive changes: \`minor\`
+- breaking changes: \`major\`
+- bugfix/clarification: \`patch\`
+
+## Compatibility Requirement
+
+Producer and consumer compatibility must be documented before release.
+`,
+        currentAssetRelativePath: "agent-state/INTERFACE_REGISTRY.md",
+    },
+];
+function normalizeForExactMatch(content) {
+    return content.replace(/\r\n/g, "\n").trimEnd();
+}
+function matchesLegacyPackageContent(content, legacyContent) {
+    return normalizeForExactMatch(content) === normalizeForExactMatch(legacyContent);
+}
+function matchesCurrentPackageContent(content, currentContent) {
+    return normalizeForExactMatch(content) === normalizeForExactMatch(currentContent);
+}
+function readAsset(assetsRoot, relativePath) {
+    return readFileSync(join(assetsRoot, relativePath), "utf-8");
+}
+export async function recordPackageGateContractVersion(store) {
+    await store.setJSON(PACKAGE_GATE_CONTRACT_VERSION_KEY, PACKAGE_GATE_CONTRACT_VERSION);
+}
+export async function migratePackageGateContract(store, workspaceRoot, assetsRoot) {
+    const messages = [];
+    let changed = false;
+    for (const entry of LEGACY_GATE_MIGRATIONS) {
+        const key = `knowledge/gates/${entry.fileName}`;
+        const currentContent = entry.currentAssetRelativePath
+            ? readAsset(assetsRoot, entry.currentAssetRelativePath)
+            : undefined;
+        const existing = await store.getBlob(key);
+        if (typeof existing === "string") {
+            if (matchesLegacyPackageContent(existing, entry.legacyContent)) {
+                if (entry.remove) {
+                    await store.delete(key);
+                    messages.push(`Removed legacy package gate ${key}.`);
+                }
+                else if (currentContent) {
+                    await store.setBlob(key, currentContent);
+                    messages.push(`Updated legacy package gate ${key}.`);
+                }
+                changed = true;
+            }
+            else if (!currentContent || !matchesCurrentPackageContent(existing, currentContent)) {
+                messages.push(`Skipped customized gate ${key}; content differs from known package seed.`);
+            }
+        }
+        const projectionPath = join(workspaceRoot, "agent-state", "MODULES", "gates", entry.fileName);
+        if (existsSync(projectionPath)) {
+            const projectionContent = readFileSync(projectionPath, "utf-8");
+            if (matchesLegacyPackageContent(projectionContent, entry.legacyContent)) {
+                if (entry.remove) {
+                    rmSync(projectionPath, { force: true });
+                    messages.push(`Removed legacy gate projection ${projectionPath}.`);
+                }
+                else if (currentContent) {
+                    mkdirSync(join(workspaceRoot, "agent-state", "MODULES", "gates"), { recursive: true });
+                    writeFileSync(projectionPath, currentContent, "utf-8");
+                    messages.push(`Updated legacy gate projection ${projectionPath}.`);
+                }
+                changed = true;
+            }
+            else if (!currentContent || !matchesCurrentPackageContent(projectionContent, currentContent)) {
+                messages.push(`Skipped customized gate projection ${projectionPath}; content differs from known package seed.`);
+            }
+        }
+    }
+    for (const entry of LEGACY_STATIC_ASSET_MIGRATIONS) {
+        const currentContent = readAsset(assetsRoot, entry.currentAssetRelativePath);
+        const existing = await store.getBlob(entry.key);
+        if (typeof existing !== "string")
+            continue;
+        if (matchesLegacyPackageContent(existing, entry.legacyContent)) {
+            await store.setBlob(entry.key, currentContent);
+            messages.push(`Updated legacy package asset ${entry.key}.`);
+            changed = true;
+        }
+        else if (!matchesCurrentPackageContent(existing, currentContent)) {
+            messages.push(`Skipped customized asset ${entry.key}; content differs from known package seed.`);
+        }
+    }
+    const recordedVersion = await store.getJSON(PACKAGE_GATE_CONTRACT_VERSION_KEY);
+    if (recordedVersion !== PACKAGE_GATE_CONTRACT_VERSION) {
+        await recordPackageGateContractVersion(store);
+        changed = true;
+    }
+    return { changed, messages };
+}
+//# sourceMappingURL=gate-contract-migration.js.map

package/dist/store/materializers/context-snapshot-materializer.d.ts

@@ -6,5 +6,6 @@ export declare class ContextSnapshotMaterializer {
     constructor(store: AcePackedStore, workspaceRoot: string);
     private directoryPath;
     materializeAll(): Promise<void>;
+    materializeAllForExport(outputDir: string): Promise<void>;
 }
 //# sourceMappingURL=context-snapshot-materializer.d.ts.map

package/dist/store/materializers/context-snapshot-materializer.js

@@ -22,7 +22,10 @@ export class ContextSnapshotMaterializer {
         return join(this.workspaceRoot, "agent-state", "context-snapshots");
     }
     async materializeAll() {
-        const dir = this.directoryPath();
+        throw new Error("Context snapshots are store-only by default. Use `ace read agent-state/context-snapshots/<name>.json --out <file>` to export a copy.");
+    }
+    async materializeAllForExport(outputDir) {
+        const dir = outputDir;
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
         const snapshots = await this.repo.listSnapshots();

package/dist/store/materializers/projection-manager.d.ts

@@ -1,5 +1,11 @@
 import { AcePackedStore } from "../ace-packed-store.js";
 export type RuntimeProjectionTarget = "context_snapshots" | "handoffs" | "ledger" | "scheduler" | "status_events" | "todo_state" | "vericify_posts" | "hook_context";
+/**
+ * Awaitable handle for the detached lifecycle sweep. CLI entry points and
+ * tests MUST await this before process exit / assertions; the MCP server may
+ * ignore it (long-lived process, sweep completes in background).
+ */
+export declare function waitForPendingLifecycleSweep(): Promise<void>;
 export declare class ProjectionManager {
     private store;
     private workspaceRoot;
@@ -7,6 +13,7 @@ export declare class ProjectionManager {
     private todoSyncer;
     private hookContext;
     private scheduler;
+    private static lifecycleSweepActive;
     constructor(store: AcePackedStore, workspaceRoot: string);
     projectAfterCommit(targets: readonly RuntimeProjectionTarget[]): Promise<void>;
 }

package/dist/store/materializers/projection-manager.js

@@ -2,6 +2,18 @@ import { HookContextMaterializer } from "./hook-context-materializer.js";
 import { SchedulerProjectionMaterializer } from "./scheduler-projection-materializer.js";
 import { TodoSyncer } from "./todo-syncer.js";
 import { VericifyProjector } from "./vericify-projector.js";
+import { cacheWorkspaceArtifacts } from "../cache-workspace.js";
+let pendingLifecycleSweep;
+let lastLifecycleSweepStartedAt = 0;
+const LIFECYCLE_SWEEP_MIN_INTERVAL_MS = 60_000;
+/**
+ * Awaitable handle for the detached lifecycle sweep. CLI entry points and
+ * tests MUST await this before process exit / assertions; the MCP server may
+ * ignore it (long-lived process, sweep completes in background).
+ */
+export function waitForPendingLifecycleSweep() {
+    return pendingLifecycleSweep ?? Promise.resolve();
+}
 export class ProjectionManager {
     store;
     workspaceRoot;
@@ -9,6 +21,7 @@ export class ProjectionManager {
     todoSyncer;
     hookContext;
     scheduler;
+    static lifecycleSweepActive = false;
     constructor(store, workspaceRoot) {
         this.store = store;
         this.workspaceRoot = workspaceRoot;
@@ -55,6 +68,30 @@ export class ProjectionManager {
         if (stagedStoreWrites) {
             await this.store.commit();
         }
+        if (stagedStoreWrites &&
+            !ProjectionManager.lifecycleSweepActive &&
+            Date.now() - lastLifecycleSweepStartedAt >= LIFECYCLE_SWEEP_MIN_INTERVAL_MS) {
+            ProjectionManager.lifecycleSweepActive = true;
+            lastLifecycleSweepStartedAt = Date.now();
+            const workspaceRoot = this.workspaceRoot;
+            // Deliberately NOT awaited: projectAfterCommit runs inside
+            // withStoreWriteCoordinator in most callers, and the sweep's own
+            // writeStoreBlobsQueued must enqueue BEHIND the current operation in the
+            // non-reentrant write queue. Awaiting here deadlocks (see
+            // REPORT_STORE_WIRING_MITIGATIONS_2026-07-09.md F1). The detached promise
+            // is exposed via waitForPendingLifecycleSweep() for CLI/test flows.
+            pendingLifecycleSweep = cacheWorkspaceArtifacts(workspaceRoot, {
+                clean: true,
+                minAgeMs: 5 * 60 * 1000,
+            })
+                .then(() => undefined)
+                .catch((error) => {
+                console.error(`ACE lifecycle sweep-lite skipped: ${error instanceof Error ? error.message : String(error)}`);
+            })
+                .finally(() => {
+                ProjectionManager.lifecycleSweepActive = false;
+            });
+        }
         for (const target of uniqueTargets) {
             if (target === "todo_state") {
                 await this.todoSyncer.writeToFile();

package/dist/store/materializers/scheduler-projection-materializer.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { operationalArtifactKey } from "../store-artifacts.js";
 import { SchedulerRepository } from "../repositories/scheduler-repository.js";
+import { isProjectedAceWorkspacePath } from "../../helpers/path-utils.js";
 function writeText(path, content) {
     const dir = dirname(path);
     if (!existsSync(dir))
@@ -40,9 +41,15 @@ export class SchedulerProjectionMaterializer {
     }
     async materializeFiles(rendered) {
         const content = rendered ?? (await this.render());
-        writeText(this.filePath("job-queue.json"), content.queue);
-        writeText(this.filePath("job-locks.json"), content.locks);
-        writeText(this.filePath("scheduler-lease.json"), content.lease);
+        if (isProjectedAceWorkspacePath("agent-state/job-queue.json")) {
+            writeText(this.filePath("job-queue.json"), content.queue);
+        }
+        if (isProjectedAceWorkspacePath("agent-state/job-locks.json")) {
+            writeText(this.filePath("job-locks.json"), content.locks);
+        }
+        if (isProjectedAceWorkspacePath("agent-state/scheduler-lease.json")) {
+            writeText(this.filePath("scheduler-lease.json"), content.lease);
+        }
     }
 }
 //# sourceMappingURL=scheduler-projection-materializer.js.map

package/dist/store/repositories/goal-repository.d.ts

@@ -0,0 +1,112 @@
+/**
+ * GoalRepository — durable storage for the ACE Goal Engine (WS-F).
+ *
+ * Persists one {@link GoalRecord} plus its active {@link TaskPlan} per goal, and
+ * a lightweight index for listing. Storage is plain JSON under
+ * `<workspaceRoot>/agent-state/goals/`, written atomically (temp + rename) so a
+ * crash mid-write never leaves a torn record — the property WS-F's resume path
+ * depends on. The repository is intentionally root-parameterized (rather than
+ * bound to the packed store) so the Goal Engine and its tests can drive it
+ * hermetically against a temp workspace.
+ *
+ * Layout:
+ *   agent-state/goals/index.json          { version, updated_at, goals: [...] }
+ *   agent-state/goals/<goal_id>.json      GoalRecord
+ *   agent-state/goals/<goal_id>.plan.json TaskPlan (rewritten every transition)
+ */
+import type { TaskPlan } from "../../orchestrator-supervisor.js";
+export type GoalStatus = "draft" | "planning" | "executing" | "verifying" | "blocked" | "done" | "failed" | "stopped";
+export type GoalEscalationKind = "approval_required" | "run_complete" | "run_error" | "gate_failed" | "budget_blocked" | "blocker";
+export interface GoalBudgets {
+    max_wall_clock_ms: number;
+    max_ticks: number;
+    max_replans: number;
+    max_step_retries: number;
+}
+export interface SuccessContract {
+    /** Union of step-level and goal-level required artifacts. */
+    expected_artifacts: Array<{
+        path: string;
+        required?: boolean;
+    }>;
+    required_evidence_refs: string[];
+    verification_commands: string[];
+    /**
+     * TODO(WS-F): wire gate_ids to execute_gates. Always `[]` today and never
+     * read, so it is deliberately excluded from `enforceableObligationCount`.
+     */
+    gate_ids: string[];
+    /**
+     * Success criteria that could not be compiled to a machine-checkable form.
+     * Never silently dropped (L3): the engine routes these to a terminal qa
+     * review step so a human/qa role adjudicates them.
+     */
+    uncompilable_criteria: string[];
+}
+export interface GoalEscalation {
+    at: string;
+    kind: GoalEscalationKind;
+    reason_code: string;
+    summary: string;
+}
+export interface GoalRecord {
+    goal_id: string;
+    objective: string;
+    status: GoalStatus;
+    plan_id?: string;
+    success_contract: SuccessContract;
+    budgets: GoalBudgets;
+    created_at: string;
+    updated_at: string;
+    started_at?: string;
+    tick_count: number;
+    replan_count: number;
+    last_heartbeat_at?: string;
+    stop_requested: boolean;
+    escalations: GoalEscalation[];
+    result_summary?: string;
+    reason_code?: string;
+    current_step_id?: string;
+}
+export interface GoalIndexEntry {
+    goal_id: string;
+    status: GoalStatus;
+    objective: string;
+    updated_at: string;
+}
+export interface GoalIndexFile {
+    version: 1;
+    updated_at: string;
+    goals: GoalIndexEntry[];
+}
+export declare function newGoalId(): string;
+export declare class GoalRepository {
+    private readonly workspaceRoot;
+    private readonly dir;
+    constructor(workspaceRoot: string);
+    private ensureDir;
+    private goalPath;
+    private planPath;
+    private indexPath;
+    private writeAtomic;
+    private readJson;
+    readIndex(): GoalIndexFile;
+    private upsertIndex;
+    /** Persist a goal record and refresh the index in one call. */
+    saveGoal(goal: GoalRecord): GoalRecord;
+    getGoal(goalId: string): GoalRecord | undefined;
+    savePlan(goalId: string, plan: TaskPlan): void;
+    getPlan(goalId: string): TaskPlan | undefined;
+    listGoals(filter?: {
+        status?: GoalStatus;
+    }): GoalIndexEntry[];
+    /** Delete a goal, its plan, and its index entry. Returns true if present. */
+    deleteGoal(goalId: string): boolean;
+    /**
+     * Rebuild the index from the on-disk goal files. Cheap self-heal used at
+     * startup so a hand-deleted or partially-written index never hides live goals.
+     */
+    rebuildIndex(): GoalIndexFile;
+}
+export declare function defaultGoalBudgets(): GoalBudgets;
+//# sourceMappingURL=goal-repository.d.ts.map