@voybio/ace-swarm 2.4.8 → 2.4.10

package/dist/host-goal-status.d.ts

@@ -0,0 +1,113 @@
+/** Read-only host status. Full records remain in the existing goal/plan owners. */
+import { type GoalEngineDeps } from './goal-engine.js';
+export declare function getCompactGoalStatus(goalId: string, agent?: string, deps?: GoalEngineDeps): {
+    goal_id: string;
+    status: import("./goal-engine.js").GoalStatus;
+    verified: boolean;
+    objective: string;
+    now: string;
+    current_step: {
+        age_ms?: number | undefined;
+        last_ace_call_at?: string | undefined;
+        contact_stale?: boolean | undefined;
+        observation?: {
+            status: "pending" | "passed" | "unmet" | "unsupported";
+            requirement: "action" | "command_pass" | undefined;
+            ref_count: number;
+            reason_code: string | undefined;
+        } | undefined;
+        step_id: string;
+        title: string;
+        status: import("./orchestrator-supervisor.js").TaskStepStatus;
+        attempt: number | undefined;
+        assignee: string | undefined;
+    } | undefined;
+    next_ready: {
+        age_ms?: number | undefined;
+        last_ace_call_at?: string | undefined;
+        contact_stale?: boolean | undefined;
+        observation?: {
+            status: "pending" | "passed" | "unmet" | "unsupported";
+            requirement: "action" | "command_pass" | undefined;
+            ref_count: number;
+            reason_code: string | undefined;
+        } | undefined;
+        step_id: string;
+        title: string;
+        status: import("./orchestrator-supervisor.js").TaskStepStatus;
+        attempt: number | undefined;
+        assignee: string | undefined;
+    }[];
+    next_ready_count: number;
+    blocked: {
+        reason: string;
+        age_ms?: number | undefined;
+        last_ace_call_at?: string | undefined;
+        contact_stale?: boolean | undefined;
+        observation?: {
+            status: "pending" | "passed" | "unmet" | "unsupported";
+            requirement: "action" | "command_pass" | undefined;
+            ref_count: number;
+            reason_code: string | undefined;
+        } | undefined;
+        step_id: string;
+        title: string;
+        status: import("./orchestrator-supervisor.js").TaskStepStatus;
+        attempt: number | undefined;
+        assignee: string | undefined;
+    }[];
+    blocked_count: number;
+    waiting_on: string[];
+    verification: {
+        failed_command_count: number;
+        failed_commands: {
+            command: string;
+            output_tail: string;
+        }[];
+        missing_artifact_count: number;
+        missing_artifacts: string[];
+        missing_evidence_count: number;
+        run?: {
+            command?: {
+                status: "done" | "running" | "failed" | "suspected_stall" | "terminating";
+                pid: number | undefined;
+                command: string;
+                elapsed_ms: number;
+                silence_ms: number;
+                output_tail: string;
+                last_output_at: string | undefined;
+            } | undefined;
+            job_id: string;
+            status: "done" | "running" | "failed" | "stopped" | "interrupted" | "queued" | "uncertain";
+            attempt: number;
+            worker: import("./process-identity.js").ProcessIdentity | undefined;
+            worker_state: "unknown" | "alive" | "dead" | undefined;
+            command_state: "unknown" | "alive" | "dead" | undefined;
+            elapsed_ms: number;
+        } | undefined;
+        status: string;
+    };
+    pending_follow_up_count: number;
+    message: string | undefined;
+    options: {
+        tool: string;
+        args: Record<string, unknown>;
+        why: string;
+    }[];
+    operator_proposal: {
+        tool: string;
+        args: Record<string, unknown>;
+        requires_operator_approval: true;
+        why: string;
+    } | undefined;
+    detail: {
+        tool: string;
+        args: {
+            goal_id: string;
+            view: string;
+        };
+        why: string;
+    };
+    previews_truncated: boolean;
+} | undefined;
+//# sourceMappingURL=host-goal-status.d.ts.map

package/dist/host-goal-status.js

@@ -0,0 +1,175 @@
+/** Read-only host status. Full records remain in the existing goal/plan owners. */
+import { resolveGoalDeps } from './goal-engine.js';
+import { resolveCurrentWork, formatCurrentWork } from './ace-autonomy.js';
+import { getReadyTaskSteps, utf8Prefix } from './task-plan-context.js';
+import { hostVerificationActive } from './host-verification-job.js';
+import { probeProcess } from './process-identity.js';
+const preview = (value, bytes) => utf8Prefix(value.replace(/\s+/g, ' ').trim(), bytes);
+function stepView(step, now) {
+    return { step_id: step.step_id, title: preview(step.task.split(/\r?\n/)[0], 160),
+        status: step.status, attempt: step.attempt, assignee: step.assignee,
+        ...(step.observation_check ? { observation: { status: step.observation_check.status, requirement: step.required_observation, ref_count: step.observation_refs?.length ?? 0, reason_code: step.observation_check.reason_code } } : {}),
+        ...(step.started_at ? { age_ms: Math.max(0, now - Date.parse(step.started_at)), last_ace_call_at: step.last_ace_call_at ?? step.started_at,
+            contact_stale: now - Date.parse(step.last_ace_call_at ?? step.started_at) >= 10 * 60000 } : {}) };
+}
+export function getCompactGoalStatus(goalId, agent, deps = {}) {
+    const d = resolveGoalDeps(deps);
+    const goal = d.repo.getGoal(goalId), plan = d.repo.getPlan(goalId);
+    if (!goal)
+        return undefined;
+    const steps = plan?.steps ?? [];
+    const ready = plan ? getReadyTaskSteps(plan) : [];
+    const running = steps.filter(s => s.status === 'running');
+    const blocked = steps.filter(s => ['blocked', 'failed'].includes(s.status));
+    const failed = (goal.verification_results ?? []).filter(r => !r.ok);
+    const check = goal.final_contract_check;
+    const workerState = goal.verification_run?.worker ? probeProcess(goal.verification_run.worker) : undefined;
+    const commandState = goal.verification_run?.command?.process ? probeProcess(goal.verification_run.command.process) : undefined;
+    const waiting = [...new Set(blocked.flatMap(s => s.waiting_on ? [s.waiting_on] : []))];
+    const options = [];
+    let operatorProposal;
+    let message;
+    if (goal.stop_requested || goal.status === 'stopped') {
+        waiting.push('user:resume');
+        message = 'Stopped. Resume only when requested.';
+    }
+    else if (goal.executor !== 'host') {
+        const budgetKind = goal.reason_code?.startsWith('goal_budget_exhausted:') ? goal.reason_code.slice('goal_budget_exhausted:'.length) : undefined;
+        const budgetExplicit = budgetKind === 'max_wall_clock' ? goal.budgets.deadline_explicit
+            : budgetKind === 'max_replans' ? goal.budgets.replan_budget_explicit
+                : budgetKind === 'max_ticks' ? goal.budgets.tick_budget_explicit : false;
+        if (budgetKind && budgetExplicit) {
+            waiting.push('operator:budget');
+            message = 'Accepted work is retained. Obtain operator approval before increasing an engine allowance; do not execute a proposal automatically.';
+            if (budgetKind === 'max_wall_clock') {
+                const hours = Math.ceil(Math.max(goal.budgets.max_wall_clock_ms, d.now() - Date.parse(goal.started_at ?? goal.created_at)) / 3600000) + 1;
+                operatorProposal = { tool: 'resume_goal', args: { goal_id: goalId, budget_hours: hours }, requires_operator_approval: true, why: 'Ask the operator to approve this total deadline from the original start before submitting it.' };
+            }
+            else if (budgetKind === 'max_replans') {
+                operatorProposal = { tool: 'resume_goal', args: { goal_id: goalId, max_replans: Math.max(goal.budgets.max_replans, goal.replan_count) + 1 }, requires_operator_approval: true, why: 'Ask the operator to approve this total replan allowance before submitting it.' };
+            }
+            else {
+                message = 'The explicit max_ticks allowance is exhausted. resume_goal does not accept a max_ticks increase; inspect full status and ask the operator to choose how to continue.';
+                options.push({ tool: 'get_goal_status', args: { goal_id: goalId, view: 'full' }, why: 'Inspect the explicit tick allowance and retained work before an operator decision.' });
+            }
+        }
+        else if (goal.status === 'executing' || goal.status === 'verifying') {
+            waiting.push('engine:execution');
+            message = 'Engine work may still be in flight. Read its status; do not start another runner from this view.';
+            options.push({ tool: 'get_goal_status', args: { goal_id: goalId, view: 'compact' }, why: 'Observe the existing engine run without assigning host steps or duplicating work.' });
+        }
+        else if (goal.reason_code === 'contract_uncheckable') {
+            waiting.push('operator:contract');
+            message = 'This success contract cannot be checked. Resume cannot repair it; inspect the retained contract before starting a goal with an artifact or verification command.';
+            options.push({ tool: 'get_goal_status', args: { goal_id: goalId, view: 'full' }, why: 'Inspect the uncheckable contract and retained work.' });
+        }
+        else if (goal.reason_code === 'repeated_failure') {
+            waiting.push('operator:repeated_failure');
+            message = goal.result_summary;
+            options.push({ tool: 'get_goal_status', args: { goal_id: goalId, view: 'full' }, why: 'Inspect repeated unchanged failures before explicitly resuming the engine.' });
+        }
+        else if (['draft', 'planning', 'blocked'].includes(goal.status)) {
+            options.push({ tool: 'resume_goal', args: { goal_id: goalId }, why: budgetKind ? 'Clear an obsolete implicit-budget blocker without increasing an allowance.' : 'Resume the engine plan after addressing its reported blocker; accepted steps remain complete.' });
+        }
+        else if (goal.status === 'failed') {
+            options.push({ tool: 'get_goal_status', args: { goal_id: goalId, view: 'full' }, why: 'Inspect the failed engine result before an operator decides how to continue.' });
+        }
+    }
+    else if (goal.reason_code?.startsWith('follow-up budget reached')) {
+        waiting.push('operator:replan_budget');
+        message = 'Follow-up admission needs an authorized replan budget; pending work is retained in full status.';
+        if (goal.pending_follow_ups?.length)
+            operatorProposal = { tool: 'resume_goal', args: { goal_id: goalId, max_replans: Math.max(goal.budgets.max_replans + 1, goal.replan_count + goal.pending_follow_ups.length) }, requires_operator_approval: true, why: 'Ask the operator to approve this total replan allowance before submitting it. Pending work is retained.' };
+        else {
+            message = 'No pending follow-up batch is available to admit. Inspect the retained requirement-change receipt; increasing a budget alone does not apply that change.';
+            options.push({ tool: 'get_goal_status', args: { goal_id: goalId, view: 'full' }, why: 'Inspect the different retained obligation before deciding how to revise it.' });
+        }
+    }
+    else if (goal.reason_code === 'host_budget_exhausted') {
+        waiting.push('operator:budget');
+        message = 'Outcomes are retained. Obtain operator approval before increasing budget_hours; do not execute the proposal automatically.';
+        const hours = Math.ceil(Math.max(goal.budgets.max_wall_clock_ms, d.now() - Date.parse(goal.started_at ?? goal.created_at)) / 3600000) + 1;
+        if (goal.budgets.host_deadline_explicit)
+            operatorProposal = { tool: 'resume_goal', args: { goal_id: goalId, budget_hours: hours }, requires_operator_approval: true, why: 'Ask the operator to approve this total hour allowance before submitting it. Accepted work is retained.' };
+        else {
+            message = 'This legacy blocker has no explicit deadline. Resume clears it without increasing any budget.';
+            options.push({ tool: 'resume_goal', args: { goal_id: goalId }, why: 'Clear a legacy default-deadline blocker; this goal has no explicit deadline.' });
+        }
+    }
+    else if (goal.status === 'verifying') {
+        if (hostVerificationActive(d.workspaceRoot, goalId)) {
+            const uncertain = goal.verification_run?.status === 'uncertain' || workerState === 'unknown' || workerState === 'dead';
+            waiting.push(uncertain ? 'operator:verification_recovery' : `verification:${goal.verification_run?.job_id ?? 'in-process'}`);
+            message = uncertain ? 'Verification ownership needs inspection. A live or uncertain command is retained; do not rerun it. Inspect full status, and resume only after old processes are confirmed gone.' : 'Final acceptance is running. Retain this execution; do not start another check.';
+            options.push({ tool: 'get_goal_status', args: { goal_id: goalId, view: 'compact', ...(agent ? { agent } : {}) }, why: 'Wait for the existing verification job and read its progress.' });
+        }
+        else {
+            message = 'Final verification was interrupted. Resume reruns only the checks after confirming the old processes are gone.';
+            options.push({ tool: 'resume_goal', args: { goal_id: goalId }, why: 'Recover interrupted verification without rerunning accepted host steps.' });
+        }
+    }
+    else if (goal.reason_code === 'repeated_failure') {
+        waiting.push('operator:repeated_failure');
+        message = goal.result_summary;
+        options.push({ tool: 'get_goal_status', args: { goal_id: goalId, view: 'full' }, why: 'Inspect repeated unchanged failures before explicitly resuming.' });
+    }
+    else if (goal.reason_code === 'observation_unmet') {
+        message = goal.result_summary;
+        options.push({ tool: 'resume_goal', args: { goal_id: goalId }, why: 'Retry evidence collection for the original accepted attempt; do not repeat the edit.' });
+    }
+    else if (blocked.some(s => s.observation_check?.status === 'unsupported')) {
+        message = 'The configured observer cannot prove the declared requirement. Inspect its capability explanation; Unknown file attribution is not a passed command or an ACE attempt link.';
+        options.push({ tool: 'get_goal_status', args: { goal_id: goalId, view: 'full' }, why: 'Inspect the unsupported observation requirement and retained outcome before changing configuration.' });
+    }
+    else if (goal.status !== 'done') {
+        if (ready.length || running.some(s => !agent || s.assignee === agent)) {
+            options.push({ tool: 'next_step', args: { goal_id: goalId, ...(agent ? { agent } : {}) }, why: 'Receive eligible corrective work or resume the existing assignment.' });
+        }
+        else if (blocked.some(s => !s.waiting_on)) {
+            options.push({ tool: 'resume_goal', args: { goal_id: goalId }, why: 'After correcting the reported blocker, make a new attempt eligible.' });
+        }
+        else if (running.length)
+            waiting.push(`agent:${preview(running[0].assignee ?? 'current owner', 120)}`);
+    }
+    const verificationStatus = goal.status === 'verifying' ? 'pending'
+        : failed.length || check?.ok === false ? 'failed'
+            : goal.verified ? 'passed' : check?.ok ? 'artifacts_checked' : 'not_required';
+    const result = {
+        goal_id: goalId, status: goal.status, verified: goal.verified ?? false,
+        objective: preview(goal.objective, 240),
+        now: formatCurrentWork(resolveCurrentWork({ workspaceRoot: d.workspaceRoot, goal_id: goalId, agent }), 'line'),
+        current_step: running[0] ? stepView(running[0], d.now()) : undefined,
+        next_ready: ready.slice(0, 3).map(s => stepView(s, d.now())), next_ready_count: ready.length,
+        blocked: blocked.slice(0, 3).map(s => ({ ...stepView(s, d.now()), reason: preview(s.blocked_reason ?? s.result_summary ?? '', 180) })),
+        blocked_count: blocked.length, waiting_on: waiting.slice(0, 3).map(s => preview(s, 160)),
+        verification: { status: verificationStatus,
+            ...(goal.verification_run ? { run: { job_id: goal.verification_run.job_id, status: goal.verification_run.status,
+                    attempt: goal.verification_run.attempt, worker: goal.verification_run.worker, worker_state: workerState, command_state: commandState,
+                    elapsed_ms: Math.max(0, d.now() - Date.parse(goal.verification_run.enqueued_at)),
+                    ...(goal.verification_run.command ? { command: { status: goal.verification_run.command.status,
+                            pid: goal.verification_run.command.pid, command: preview(goal.verification_run.command.command, 160),
+                            elapsed_ms: Math.max(0, d.now() - Date.parse(goal.verification_run.command.started_at)),
+                            silence_ms: Math.max(0, d.now() - Date.parse(goal.verification_run.command.last_progress_at)),
+                            output_tail: utf8Prefix(goal.verification_run.command.output_tail.slice(-600), 500),
+                            last_output_at: goal.verification_run.command.last_output_at } } : {}) } } : {}), failed_command_count: failed.length,
+            failed_commands: failed.slice(0, 2).map(r => ({ command: preview(r.command, 160), output_tail: utf8Prefix(r.output.slice(-600), 300) })),
+            missing_artifact_count: check?.missing_artifacts.length ?? 0,
+            missing_artifacts: check?.missing_artifacts.slice(0, 3).map(p => preview(p, 160)) ?? [],
+            missing_evidence_count: check?.missing_evidence_refs.length ?? 0 },
+        pending_follow_up_count: goal.pending_follow_ups?.length ?? 0,
+        message, options, operator_proposal: operatorProposal,
+        detail: { tool: 'get_goal_status', args: { goal_id: goalId, view: 'full' }, why: 'Retrieve complete plan, attempts and verification evidence.' },
+        previews_truncated: false,
+    };
+    // Keep counts, the primary failure, executable actions and full-record locator.
+    // Only optional previews shrink when several dense categories coexist.
+    const bytes = () => Buffer.byteLength(JSON.stringify(result));
+    for (const previews of [result.next_ready, result.blocked, result.verification.missing_artifacts, result.verification.failed_commands]) {
+        while (bytes() > 4096 && previews.length > 1) {
+            previews.pop();
+            result.previews_truncated = true;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=host-goal-status.js.map

package/dist/host-learning.d.ts

@@ -0,0 +1,68 @@
+import type { TaskStep, StepAttempt } from './orchestrator-supervisor.js';
+import { type GoalRecord } from './store/repositories/goal-repository.js';
+import { type PlaybookScope } from './store/repositories/playbook-repository.js';
+export interface Episode {
+    id: string;
+    attempt?: number;
+    goal_id: string;
+    step_id: string;
+    role: string;
+    task: string;
+    paths: string[];
+    tags: string[];
+    status: StepAttempt['status'];
+    summary: string;
+    failure_signature?: string;
+    failure_excerpt?: string;
+    evidence_refs: string[];
+    served?: string[];
+    at: string;
+    observed_runs?: StepAttempt['observed_runs'];
+    checks?: Array<{
+        command: string;
+        cwd: string;
+        ok: boolean;
+    }>;
+    scope_snapshot?: StepAttempt['scope_snapshot'];
+    served_context?: StepAttempt['served_context'];
+    provenance?: string;
+}
+export declare function appendAttempt(step: TaskStep, _goal: Pick<GoalRecord, 'goal_id'>, at: string, checks?: StepAttempt['checks']): void;
+export declare function listEpisodes(root: string, options?: {
+    since?: string;
+    scope?: PlaybookScope;
+}): Episode[];
+export declare function compactEpisode(ep: Episode): Episode;
+export declare function harvestStep(root: string, goal: GoalRecord, step: TaskStep): Promise<void>;
+export interface HostLessonInput {
+    context: string;
+    failure_pattern: string;
+    guardrail: string;
+    verification_check: string;
+    evidence_refs?: string[];
+    step_ref?: {
+        goal_id: string;
+        step_id: string;
+    };
+    paths?: string[];
+}
+export declare function addHostLesson(root: string, input: HostLessonInput): Promise<{
+    bullet: import("./store/repositories/playbook-repository.js").PlaybookBullet;
+    options: {
+        tool: string;
+        args: {
+            context: string;
+            failure_pattern: string;
+            guardrail: string;
+            verification_check: string;
+            evidence_refs?: string[];
+            step_ref?: {
+                goal_id: string;
+                step_id: string;
+            };
+            paths?: string[];
+        };
+        why: string;
+    }[];
+}>;
+//# sourceMappingURL=host-learning.d.ts.map

package/dist/host-learning.js

@@ -0,0 +1,115 @@
+import { utf8Prefix } from './task-plan-context.js';
+import { parse as parseYaml } from 'yaml';
+import { readLearningPolicy } from './learning-policy.js';
+/** Learning over existing host goal plans and playbook records; no capture or model calls. */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { resolve, isAbsolute, relative } from 'node:path';
+import { GoalRepository } from './store/repositories/goal-repository.js';
+import { withPlaybookTransaction } from './store/repositories/playbook-repository.js';
+import { readStoreBlobSync, listStoreKeysSync } from './store/store-snapshot.js';
+import { operationalArtifactKey } from './store/store-artifacts.js';
+import { failureSignature, normalizedFailureLines, reflectFromStepOutcome, learningTaskText } from './experience-reflector.js';
+import { curate } from './playbook-curator.js';
+const tags = ['test', 'build', 'store', 'todo', 'handoff', 'scheduler', 'migration', 'docs', 'release', 'mcp', 'hook', 'schema'];
+export function appendAttempt(step, _goal, at, checks) {
+    const runs = step.observation_refs?.filter(r => r.attribution === 'Linked' && r.run?.attribution === 'Linked').flatMap(r => r.run ? [{ ...r.run, record_id: r.id }] : []).slice(-20);
+    const failure = runs?.filter(r => r.outcome === 'failed').map(r => r.output_tail ?? '').join('\n') || (step.status !== 'done' ? step.blocked_reason ?? step.result_summary ?? '' : '');
+    const scope_snapshot = stepScope(step, step.evidence_refs ?? [], checks);
+    const served_context = step.served_learning ? { items: step.served_learning.items.map(({ id, kind, scope }) => ({ id, kind, scope: structuredClone(scope) })), rendered_bytes: Buffer.byteLength(step.served_learning.text) } : undefined;
+    const entry = { attempt: step.attempt ?? 0, status: step.status === 'done' ? 'done' : step.status === 'blocked' ? 'blocked' : 'failed', at, summary: (step.result_summary ?? '').slice(0, 600), checks, scope_snapshot, served_context, evidence_refs: step.evidence_refs ?? [], served: step.served_learning?.items.map(i => i.id), failure_signature: failureSignature(failure), failure_excerpt: normalizedFailureLines(failure).slice(0, 6).join('\n') || undefined, ...(runs?.length ? { observed_runs: runs } : {}) };
+    step.attempts_log = [...(step.attempts_log ?? []).filter(e => e.attempt !== entry.attempt), entry].slice(-5);
+}
+function stepScope(step, refs, checks) {
+    const paths = [...new Set([...(step.expected_artifacts ?? []).map(a => a.path), ...refs.filter(ref => !/^(ep:|ace:|goal:|https?:|vericify:)/.test(ref))].map(path => path.replace(/\\/g, '/').replace(/^\.\//, '')))];
+    const task = checks?.length ? checks.map(c => c.command).join('\n') : learningTaskText(step);
+    return { role: step.role, paths, task_tags: tags.filter(tag => task.toLowerCase().includes(tag)) };
+}
+function episode(goal, step, entry) {
+    const scope = entry.scope_snapshot ?? stepScope(step, entry.evidence_refs, entry.checks);
+    return { id: `ep:${goal}:${step.step_id}:${entry.attempt}`, goal_id: goal, step_id: step.step_id, role: scope.role, task: step.task.slice(0, 600), paths: scope.paths, tags: scope.task_tags, ...entry, summary: entry.summary.slice(0, 600), provenance: 'ACE plan attempt; external references retain their own attribution and retention' };
+}
+export function listEpisodes(root, options = {}) {
+    const goals = new GoalRepository(root), rows = new Map();
+    // Reading a playbook through its mutating legacy migration API is forbidden here.
+    const keys = listStoreKeysSync(root, operationalArtifactKey('agent-state/playbook/'));
+    for (const key of keys) {
+        try {
+            const record = JSON.parse(readStoreBlobSync(root, key) ?? '{}');
+            for (const ep of record.evidence_snapshots ?? [])
+                rows.set(ep.id, ep);
+        }
+        catch { /* malformed historical record is not an episode */ }
+    }
+    for (const key of listStoreKeysSync(root, 'knowledge/').filter(k => /(?:\/SKILL\.md|\/LEARNED\.md|\/references\/proposals\/[^/]+\.md)$/.test(k))) {
+        try {
+            const raw = readStoreBlobSync(root, key) ?? '';
+            const front = parseYaml(raw.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? '');
+            for (const ep of front?.ace_learning?.evidence_snapshots ?? [])
+                if (!rows.has(ep.id))
+                    rows.set(ep.id, ep);
+        }
+        catch { /* Retained external IDs remain unavailable; no fabricated readback. */ }
+    }
+    // Standalone workspaces retain the same playbook records on disk.
+    const legacy = resolve(root, 'agent-state/playbook');
+    if (existsSync(legacy))
+        for (const name of readdirSync(legacy).filter(n => n.endsWith('.json') && n !== '__index.json')) {
+            try {
+                const bullet = JSON.parse(readFileSync(resolve(legacy, name), 'utf8'));
+                for (const ep of bullet.evidence_snapshots ?? [])
+                    if (!rows.has(ep.id))
+                        rows.set(ep.id, ep);
+            }
+            catch { /* unavailable record remains unavailable */ }
+        }
+    for (const g of goals.listGoals())
+        for (const s of goals.getPlan(g.goal_id)?.steps ?? [])
+            for (const entry of s.attempts_log ?? [])
+                rows.set(`ep:${g.goal_id}:${s.step_id}:${entry.attempt}`, episode(g.goal_id, s, entry));
+    return [...rows.values()].filter(e => (!options.since || e.at >= options.since) && (!options.scope?.role || e.role === options.scope.role) && (!options.scope?.failure_signature || e.failure_signature === options.scope.failure_signature) && (!options.scope?.task_tags?.length || e.tags.some(t => options.scope.task_tags.includes(t))) && (!options.scope?.paths?.length || e.paths.some(p => options.scope.paths.some(q => p === q || p.startsWith(q + '/'))))).sort((a, b) => a.at.localeCompare(b.at));
+}
+export function compactEpisode(ep) {
+    // Full immutable command bodies stay with Vericify; pin only ACE work context.
+    const { observed_runs: _, ...compact } = ep;
+    return { ...compact, task: utf8Prefix(compact.task, 200), summary: utf8Prefix(compact.summary, 600), failure_excerpt: compact.failure_excerpt ? utf8Prefix(compact.failure_excerpt, 200) : undefined };
+}
+export async function harvestStep(root, goal, step) {
+    if (!readLearningPolicy(root).enabled)
+        return;
+    const all = listEpisodes(root), ops = reflectFromStepOutcome(step, goal);
+    const current = all.filter(e => e.goal_id === goal.goal_id && e.step_id === step.step_id).at(-1);
+    if (current?.status === 'blocked' && current.failure_signature) {
+        const blockers = all.filter(e => e.status === 'blocked' && e.failure_signature === current.failure_signature);
+        if (new Set(blockers.map(e => `${e.goal_id}:${e.step_id}`)).size >= 2)
+            ops.push({ type: 'ADD', section: 'strategies', status: 'quarantined', scope: { role: step.role, failure_signature: current.failure_signature, paths: current.paths.map(p => p.split('/').slice(0, 2).join('/')), task_tags: current.tags }, content: `Repeated blocker: ${current.failure_excerpt ?? current.summary}. Compare the cited blocked steps before selecting a recovery.`, evidence_refs: blockers.map(e => e.id), provenance: { source: 'harvest', run_id: `blocker:${current.failure_signature}` } });
+    }
+    if (!ops.length)
+        return;
+    await withPlaybookTransaction(root, async (repo) => {
+        const existing = repo.listBullets();
+        const fresh = ops.filter(op => op.type === 'ADD' && !existing.some(b => b.provenance.source === 'harvest' && b.provenance.run_id === op.provenance.run_id && b.scope.failure_signature === op.scope.failure_signature));
+        for (const op of fresh)
+            if (op.type === 'ADD')
+                op.evidence_snapshots = all.filter(e => op.evidence_refs.includes(e.id)).map(compactEpisode);
+        if (fresh.length)
+            await curate(repo, fresh, { workspaceRoot: root, emitEvent: false });
+    });
+    const { ensureLearningStep } = await import('./learned-artifacts.js');
+    await ensureLearningStep(root);
+}
+export async function addHostLesson(root, input) {
+    const episodes = input.step_ref ? listEpisodes(root).filter(e => e.goal_id === input.step_ref.goal_id && e.step_id === input.step_ref.step_id) : [];
+    const evidence = [...new Set([...(input.evidence_refs ?? []), ...episodes.map(e => e.id)])];
+    const resolves = (ref) => {
+        if (ref.startsWith('ep:'))
+            return listEpisodes(root).some(e => e.id === ref);
+        const p = resolve(root, ref);
+        if (isAbsolute(relative(root, p)) || relative(root, p).startsWith('..'))
+            return false;
+        return existsSync(p) || readStoreBlobSync(root, ref) !== undefined || readStoreBlobSync(root, operationalArtifactKey(ref)) !== undefined;
+    };
+    const active = episodes.some(e => e.failure_signature && e.status !== 'done') || (input.evidence_refs ?? []).some(resolves);
+    const bullet = await withPlaybookTransaction(root, repo => repo.createBullet({ section: 'failure_modes', scope: { paths: input.paths?.map(p => p.replace(/\\/g, '/').split('/').slice(0, 2).join('/')), failure_signature: episodes.find(e => e.failure_signature)?.failure_signature }, content: `${input.guardrail}\nWhy: ${input.failure_pattern}\nCheck: ${input.verification_check}`, evidence_refs: evidence, status: active ? 'active' : 'quarantined', provenance: { source: 'operator', note: input.context }, evidence_snapshots: episodes.map(compactEpisode), label: active ? 'checked' : undefined }));
+    return { bullet, options: active ? [] : [{ tool: 'add_lesson', args: { ...input }, why: 'Attach resolvable evidence_refs or step_ref to activate this lesson.' }] };
+}
+//# sourceMappingURL=host-learning.js.map

package/dist/host-observation.d.ts

@@ -0,0 +1,12 @@
+/** Evidence collection is acceptance work, never another execution of the host's edit. */
+import type { GoalEngineDeps } from './goal-engine.js';
+import type { TaskPlan, TaskStep } from './orchestrator-supervisor.js';
+export declare function observationSatisfied(step: TaskStep, records: NonNullable<TaskStep['observation_refs']>): boolean;
+export declare function pendingObservation(step: TaskStep): boolean;
+export declare function recoverableObservation(step: TaskStep): boolean;
+export declare function observationAdapter(root: string, deps: GoalEngineDeps): GoalEngineDeps['observations'];
+export declare function retainObservation(step: TaskStep, result: Awaited<ReturnType<NonNullable<GoalEngineDeps['observations']>['readWindow']>>): void;
+/** Uses the existing goal.verify worker and lease; no watcher, timer daemon or history store. */
+export declare function settleHostObservations(goalId: string, generation: number | undefined, deps: GoalEngineDeps): Promise<boolean>;
+export declare function observationReadyForChecks(plan: TaskPlan): boolean;
+//# sourceMappingURL=host-observation.d.ts.map

package/dist/host-observation.js

@@ -0,0 +1,91 @@
+import { resolveGoalDeps } from './goal-engine.js';
+import { configuredObservationAdapter } from './vericify-context.js';
+import { deriveTaskPlanStatus } from './orchestrator-supervisor.js';
+import { withStoreWriteCoordinator } from './store/write-coordinator.js';
+export function observationSatisfied(step, records) {
+    return records.some(r => r.attribution === 'Linked' && (step.required_observation === 'action' || (r.kind === 'command' && r.result === 'passed')));
+}
+export function pendingObservation(step) {
+    const check = step.observation_check;
+    return !!check && check.attempt === step.attempt && check.status === 'pending';
+}
+export function recoverableObservation(step) {
+    const check = step.observation_check;
+    return !!check && check.attempt === step.attempt && ['pending', 'unmet', 'unsupported'].includes(check.status);
+}
+export function observationAdapter(root, deps) {
+    return deps.observations ?? configuredObservationAdapter(root);
+}
+export function retainObservation(step, result) {
+    step.observation = result.status;
+    step.observation_refs = result.records;
+    if (result.query)
+        step.observation_query = result.query;
+    if (result.coverage)
+        step.observation_coverage = result.coverage;
+}
+/** Uses the existing goal.verify worker and lease; no watcher, timer daemon or history store. */
+export async function settleHostObservations(goalId, generation, deps) {
+    const d = resolveGoalDeps(deps), adapter = observationAdapter(d.workspaceRoot, deps);
+    for (;;) {
+        const goal = d.repo.getGoal(goalId), plan = d.repo.getPlan(goalId);
+        if (!goal || !plan || goal.verification_attempt !== generation || goal.stop_requested || goal.status !== 'verifying')
+            return false;
+        const step = plan.steps.find(pendingObservation);
+        if (!step)
+            return true;
+        const window = step.observation_window && { ...step.observation_window };
+        let read = { status: 'unavailable', records: [], reason_code: 'observation_adapter_unavailable' };
+        if (adapter && window) {
+            try {
+                read = await adapter.readWindow(window);
+            }
+            catch {
+                read = { status: 'unavailable', records: [], reason_code: 'observation_query_failed' };
+            }
+        }
+        let wait = 0, settled = false;
+        await withStoreWriteCoordinator(d.repo.planPath(goalId), async () => {
+            const current = d.repo.getGoal(goalId), fresh = d.repo.getPlan(goalId), target = fresh?.steps.find(s => s.step_id === step.step_id);
+            if (!current || !fresh || !target || current.stop_requested || current.status !== 'verifying' || current.verification_attempt !== generation || target.attempt !== step.attempt || !pendingObservation(target) || JSON.stringify(target.observation_window) !== JSON.stringify(window)) {
+                settled = true;
+                return;
+            }
+            retainObservation(target, read);
+            const check = target.observation_check;
+            if (observationSatisfied(target, read.records)) {
+                check.status = 'passed';
+                check.reason_code = undefined;
+                target.status = 'done';
+                target.waiting_on = undefined;
+                target.blocked_reason = undefined;
+            }
+            else if (d.now() >= Date.parse(check.deadline_at) || !adapter) {
+                check.status = 'unmet';
+                check.reason_code = read.reason_code ?? 'required_observation_missing';
+                target.status = 'blocked';
+                target.waiting_on = 'operator:observation';
+                target.blocked_reason = `Required ${target.required_observation} observation is unmet (${check.reason_code}). Resume retries evidence collection for this accepted attempt; do not repeat the edit.`;
+                current.status = 'blocked';
+                current.reason_code = 'observation_unmet';
+                current.result_summary = target.blocked_reason;
+                if (current.verification_run)
+                    current.verification_run.status = 'failed';
+                settled = true;
+            }
+            else
+                wait = Math.min(check.poll_ms, Math.max(1, Date.parse(check.deadline_at) - d.now()));
+            fresh.status = deriveTaskPlanStatus(fresh);
+            d.repo.savePlan(goalId, fresh);
+            d.repo.saveGoal(current);
+        }, { operation_label: 'host_observation_acceptance' });
+        if (settled)
+            return false;
+        if (wait)
+            await d.sleep(wait);
+    }
+}
+export function observationReadyForChecks(plan) {
+    return plan.steps.every(s => ['done', 'skipped'].includes(s.status));
+}
+//# sourceMappingURL=host-observation.js.map

package/dist/host-plan-revision.d.ts

@@ -0,0 +1,14 @@
+import { type TaskPlan, type TaskStep } from "./orchestrator-supervisor.js";
+export type HostRequirementUpdate = {
+    step_id: string;
+    reason: string;
+    task?: string;
+    expected_artifacts?: TaskStep["expected_artifacts"];
+    required_evidence_refs?: string[];
+};
+/** Prepare a requirement change; the caller owns persistence and execution. */
+export declare function reviseHostRequirements(plan: TaskPlan, updates: HostRequirementUpdate[]): {
+    plan: TaskPlan;
+    reopened: string[];
+};
+//# sourceMappingURL=host-plan-revision.d.ts.map