brainclaw 1.26.2 → 1.27.0

package/dist/core/loops/index.js

@@ -1,4 +1,10 @@
 export * from './types.js';
+export * from './attempt-generations.js';
+export * from './attempt-rollout.js';
+export * from './attempt-takeover.js';
+export { GATE_POLICY_VERSION, artifactEvidenceProvenance, artifactEvidenceDigest, evidenceDigest, evidencePolicyForNewLoop, evidenceWriterEnabled, validateArtifactEvidence, validateThreadEvidence, } from './evidence.js';
+export { GATE_POLICIES, eligibleArtifactsForPurpose, evaluateCommandGreen, evaluateCriticSignal, evaluateGateCondition, evaluateNoNewCritique, } from './gate-policy.js';
+export { EXECUTION_CONTRACT_PROTOCOL_VERSION, EXECUTION_CONTRACT_VERSION, CapabilityRequirementSchema, CapabilityResolutionReasonSchema, CapabilitySnapshotSchema, HarnessCapabilityBindingSchema, ExecutionContractRefSchema, ExecutionContractSchema, RuntimeCapabilityObservationSchema, assertExecutionContractIntegrity, capabilitySnapshotHash, canonicalExecutionContract, executionContractHash, executionContractRef, resolveCapabilitySnapshot, validateWorkerContractAcceptance, } from '../execution-contract.js';
 export { AwaitingFileApplyApprovalError, closeLoop, ensureLoopsDir, generateLoopId, generateMutationId, generateSlotId, getLoop, listLoopEvents, listLoops, openLoop, writeThreadFile, } from './store.js';
 export { add_artifact, advance, complete_turn, evaluatePhaseAdvanceGate, evaluateStopCondition, pause, provideInput, reconcileOpenQuestions, requestInput, resume, sweepPauseTimeouts, turn, } from './verbs.js';
 export { decideNextPhase, artifactsInIteration, noNewCritiqueInIteration, hasCriticSignalInIteration, hasPassingVerifyReportInIteration, } from './iteration-engine.js';
@@ -12,4 +18,7 @@ export { buildSurveySignalsBaseline, } from './hooks/survey-signals-baseline.js'
 export { acquireLock, hashRequest, recordConflict, withLoopLock, DEFAULT_MAX_MUTATION_DURATION_MS, IDEMPOTENCY_TTL_MS, LEASE_GRACE_MS, LEASE_WINDOW_MS, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, LockLostError, LockTimeoutError, VersionConflictError, } from './lock.js';
 export { acquireBootstrapLoop, findExistingBootstrapLoop, BootstrapCoordinationInProgressError, } from './bootstrap-acquire.js';
 export { deriveWorkerReplyContract, renderWorkerReplyProse, workerReplyNextAction, } from './worker-reply-contract.js';
+export { abortAttempt, inspectAttempt, matchEvidence, prepareAttempt, projectAndCross, revokeAttempt, } from './attempt-authority.js';
+export { LOOP_KIND_POLICIES, assertLoopKindPoliciesComplete, isWorkerPhase, phasePolicy, policyForKind, } from './kind-policies.js';
+export { ensureTurnExecutionProjections, prepareTurnExecution, } from './turn-execution.js';
 //# sourceMappingURL=index.js.map

package/dist/core/loops/iteration-engine.js

@@ -12,6 +12,7 @@
  * transitions = exit_when conditions + cycle membership, guards = phase
  * advance_gate, actions = system event emissions.
  */
+import { evaluateCommandGreen, evaluateCriticSignal, evaluateNoNewCritique, } from './gate-policy.js';
 /**
  * Decide the next phase given the current thread state and the protocol.
  *
@@ -19,7 +20,7 @@
  * is no successor (last phase + no iteration block). Callers that want
  * to handle "already at end" should check beforehand.
  */
-export function decideNextPhase(thread, protocol) {
+export function decideNextPhase(thread, protocol, cwd) {
     const phaseNames = protocol.phases.map((p) => p.name);
     const currentIndex = phaseNames.indexOf(thread.current_phase);
     if (currentIndex < 0) {
@@ -44,6 +45,26 @@ export function decideNextPhase(thread, protocol) {
     //       exit by max_iterations.
     const cycleIndex = cycle.indexOf(thread.current_phase);
     const atCycleEnd = cycleIndex === cycle.length - 1;
+    // A saturation exit is a negative observation: after at least one full
+    // cycle, a settled critique phase with no eligible new critique exits
+    // directly. Waiting until the revision boundary made this condition
+    // unreachable because the critique phase's quantitative gate refused the
+    // very zero-artifact round the exit condition needs to observe.
+    if (cycleIndex === 0 &&
+        thread.iteration_count > 0 &&
+        protocol.iteration?.exit_when === 'no_new_critique_artifacts' &&
+        noNewCritiqueInIteration(thread, thread.iteration_count, cwd)) {
+        const lastCyclePhaseIndex = phaseNames.indexOf(cycle[cycle.length - 1]);
+        if (lastCyclePhaseIndex < 0 || lastCyclePhaseIndex + 1 >= phaseNames.length) {
+            throw new Error(`decideNextPhase: cycle's last phase "${cycle[cycle.length - 1]}" has no post-cycle successor`);
+        }
+        return {
+            kind: 'exit_cycle',
+            target: phaseNames[lastCyclePhaseIndex + 1],
+            iteration: thread.iteration_count,
+            reason: 'no_new_critique_artifacts',
+        };
+    }
     if (!atCycleEnd) {
         return {
             kind: 'advance_to',
@@ -75,7 +96,7 @@ export function decideNextPhase(thread, protocol) {
     // iteration_count is the one that just completed (the engine has not
     // yet incremented).
     if (iterationBlock.exit_when === 'critic_signal' &&
-        hasCriticSignalInIteration(thread, thread.iteration_count)) {
+        hasCriticSignalInIteration(thread, thread.iteration_count, cwd)) {
         return {
             kind: 'exit_cycle',
             target: postCycleTarget,
@@ -84,7 +105,7 @@ export function decideNextPhase(thread, protocol) {
         };
     }
     if (iterationBlock.exit_when === 'no_new_critique_artifacts' &&
-        noNewCritiqueInIteration(thread, thread.iteration_count)) {
+        noNewCritiqueInIteration(thread, thread.iteration_count, cwd)) {
         return {
             kind: 'exit_cycle',
             target: postCycleTarget,
@@ -93,7 +114,7 @@ export function decideNextPhase(thread, protocol) {
         };
     }
     if (iterationBlock.exit_when === 'command_green' &&
-        hasPassingVerifyReportInIteration(thread, thread.iteration_count)) {
+        hasPassingVerifyReportInIteration(thread, thread.iteration_count, cwd)) {
         return {
             kind: 'exit_cycle',
             target: postCycleTarget,
@@ -134,16 +155,16 @@ export function artifactsInIteration(thread, iteration) {
  * just-completed iteration produced no critique-typed artifacts. Used
  * by `decideNextPhase` at the cycle boundary.
  */
-export function noNewCritiqueInIteration(thread, iteration) {
-    return !thread.artifacts.some((a) => (a.iteration ?? 0) === iteration && a.type === 'critique');
+export function noNewCritiqueInIteration(thread, iteration, cwd) {
+    return evaluateNoNewCritique(thread, iteration, cwd).passed;
 }
 /**
  * `exit_when='critic_signal'` predicate: true when the iteration
  * contains a `type='critic_signal'` artifact (any subtype/body). The
  * critic emits this when it judges the proposal sufficient.
  */
-export function hasCriticSignalInIteration(thread, iteration) {
-    return thread.artifacts.some((a) => (a.iteration ?? 0) === iteration && a.type === 'critic_signal');
+export function hasCriticSignalInIteration(thread, iteration, cwd) {
+    return evaluateCriticSignal(thread, iteration, cwd).passed;
 }
 /**
  * `exit_when='command_green'` predicate (pln#609): true when the just-finished
@@ -153,16 +174,7 @@ export function hasCriticSignalInIteration(thread, iteration) {
  * Increment 2). Iteration-window scoped so a green from a prior iteration can
  * never satisfy the current one; absence reads as false.
  */
-export function hasPassingVerifyReportInIteration(thread, iteration) {
-    return artifactsInIteration(thread, iteration).some((a) => {
-        if (a.type !== 'verify_report')
-            return false;
-        try {
-            return JSON.parse(a.body ?? '{}').passed === true;
-        }
-        catch {
-            return false;
-        }
-    });
+export function hasPassingVerifyReportInIteration(thread, iteration, cwd) {
+    return evaluateCommandGreen(thread, iteration, cwd).passed;
 }
 //# sourceMappingURL=iteration-engine.js.map

package/dist/core/loops/kind-policies.js

@@ -0,0 +1,90 @@
+import { DEFAULT_PROTOCOLS, LOOP_KINDS } from './types.js';
+const expected = (logicalName, loopArtifactType = logicalName) => ({
+    logical_name: logicalName,
+    worker_path: 'LANE-RESULT.json',
+    loop_artifact_type: loopArtifactType,
+    completion_policy: 'required',
+});
+/**
+ * Execution metadata only. DEFAULT_PROTOCOLS remains canonical for phase
+ * graphs, advance gates, iteration and stop conditions.
+ */
+export const LOOP_KIND_POLICIES = {
+    review: {
+        phases: {
+            change_summary: { execution: 'manual' },
+            findings: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('review_verdict', 'verdict')], finalization: 'report' },
+            author_response: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('author_response')], finalization: 'integrate' },
+            followup_review: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('review_verdict', 'verdict')], finalization: 'report' },
+            verdict: { execution: 'engine' },
+        },
+    },
+    ideation: {
+        phases: {
+            proposal: { execution: 'manual' },
+            critique: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('critique')], finalization: 'report' },
+            // Critic and champion work use the same generic production driver. The
+            // coordinator still chooses when to cross each phase; the worker only
+            // produces the declared artifact and never advances the loop.
+            revision: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('revision')], finalization: 'report' },
+            synthesis: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('plan_draft')], finalization: 'report' },
+        },
+    },
+    implementation: {
+        phases: {
+            bind: { execution: 'engine' },
+            execute: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('execute_report')], finalization: 'integrate' },
+            verify: { execution: 'engine' },
+            handoff_ready: { execution: 'manual' },
+        },
+    },
+    research: {
+        phases: {
+            investigate: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('finding')], finalization: 'report' },
+            synthesize: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('synthesis')], finalization: 'report' },
+            conclude: { execution: 'engine' },
+        },
+    },
+    debug: {
+        phases: {
+            reproduce: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('repro')], finalization: 'report' },
+            hypothesize: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('hypothesis')], finalization: 'report' },
+            isolate: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('isolation_report')], finalization: 'report' },
+            fix: { execution: 'worker', completion_mode: 'either', expected_artifacts: [expected('verify_report')], finalization: 'integrate' },
+            handoff: { execution: 'manual' },
+        },
+    },
+};
+export function policyForKind(kind) {
+    return LOOP_KIND_POLICIES[kind];
+}
+export function phasePolicy(kind, phase) {
+    return LOOP_KIND_POLICIES[kind].phases[phase];
+}
+export function isWorkerPhase(kind, phase) {
+    return phasePolicy(kind, phase)?.execution === 'worker';
+}
+/** Runtime assertion used by conformance tests and startup diagnostics. */
+export function assertLoopKindPoliciesComplete() {
+    for (const kind of LOOP_KINDS) {
+        const policy = LOOP_KIND_POLICIES[kind];
+        if (!policy)
+            throw new Error(`missing LoopKindPolicy for ${kind}`);
+        const protocolPhases = DEFAULT_PROTOCOLS[kind].phases.map((phase) => phase.name).sort();
+        const policyPhases = Object.keys(policy.phases).sort();
+        if (JSON.stringify(protocolPhases) !== JSON.stringify(policyPhases)) {
+            throw new Error(`${kind} policy phases diverge from DEFAULT_PROTOCOLS: policy=${policyPhases.join(',')} protocol=${protocolPhases.join(',')}`);
+        }
+        for (const [phase, phaseExecution] of Object.entries(policy.phases)) {
+            if (phaseExecution.execution === 'worker') {
+                if (!phaseExecution.completion_mode || !phaseExecution.expected_artifacts?.length || !phaseExecution.finalization) {
+                    throw new Error(`${kind}.${phase} worker policy is incomplete`);
+                }
+            }
+            else if (phaseExecution.completion_mode || phaseExecution.expected_artifacts?.length || phaseExecution.finalization) {
+                throw new Error(`${kind}.${phase} ${phaseExecution.execution} policy must not declare worker execution metadata`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=kind-policies.js.map

package/dist/core/loops/lock.js

@@ -9,9 +9,11 @@ import { recoverPendingIntents } from './commit-intent.js';
  * Per-loop exclusive lock + idempotency + fencing helpers.
  *
  * Implements the commit protocol from docs/concepts/loop-engine.md §Persistence.
- * For synchronous MVP mutations, the lock window is short (< 100ms typically) so
- * lease renewal via an internal heartbeat is not yet wired up; the hard_deadline
- * is still recorded in the lock blob and used by the stale-lock recovery rules.
+ * For synchronous mutations, the lock window is short (< 100ms typically), so
+ * lease renewal via an internal heartbeat is not wired up. `lease_until` and
+ * `hard_deadline` remain durable diagnostics, but elapsed time alone never
+ * authorizes automatic takeover: without per-write fencing, a suspended live
+ * process could otherwise resume after takeover and commit as a second owner.
  */
 export const LOCK_BACKOFF_BASE_MS = 10;
 export const LOCK_BACKOFF_TOTAL_MS = 500;
@@ -179,14 +181,70 @@ function processIsAlive(pid) {
         return code === 'EPERM';
     }
 }
-function lockIsStale(blob, now) {
-    if (now > Date.parse(blob.hard_deadline))
-        return true;
-    if (blob.host_id === os.hostname() && !processIsAlive(blob.pid))
-        return true;
-    if (now > Date.parse(blob.lease_until) + LEASE_GRACE_MS)
-        return true;
-    return false;
+function lockIsStale(blob, _now) {
+    // Automatic reaping is deliberately proof-based. On the local host we can
+    // prove the owning process is gone. A deadline or lease expiry only proves
+    // that a process was delayed; on Windows a suspended live process can resume.
+    // Cross-host liveness is likewise unknowable from this file alone, so those
+    // locks fail closed and require explicit operator recovery.
+    return blob.host_id === os.hostname() && !processIsAlive(blob.pid);
+}
+function takeoverClaimPath(lockPath, observedMutationId) {
+    // Lock blobs are read from disk and may predate schema validation. Hash the
+    // token before using it as a filename so a corrupt value cannot escape the
+    // takeover directory or create a Windows-invalid path.
+    const generationKey = crypto.createHash('sha256').update(observedMutationId).digest('hex');
+    return path.join(`${lockPath}.takeovers`, `${generationKey}.lock`);
+}
+/**
+ * Remove exactly the stale generation that was observed.
+ *
+ * A plain `read stale -> unlink(path)` has an ABA race on Windows: another
+ * reaper can replace generation X with Y between the read and unlink, after
+ * which the late reaper deletes Y. The immutable, generation-keyed takeover
+ * claim elects one reaper for X. Losers never unlink the shared path.
+ *
+ * If the elected reaper crashes before unlinking, the generation fails closed
+ * (the tiny takeover claim is retained for operator recovery). If it crashes
+ * after unlinking, contenders can safely acquire the now-empty main path.
+ */
+function reapObservedLock(lockPath, observed, agentId) {
+    const nowMs = Date.now();
+    const claimPath = takeoverClaimPath(lockPath, observed.mutation_id);
+    const claim = {
+        pid: process.pid,
+        host_id: os.hostname(),
+        agent_id: agentId,
+        acquired_at: new Date(nowMs).toISOString(),
+        lease_until: new Date(nowMs + LEASE_WINDOW_MS).toISOString(),
+        hard_deadline: new Date(nowMs + 5_000).toISOString(),
+        mutation_id: crypto.randomUUID().replace(/-/g, ''),
+    };
+    if (!acquireRaw(claimPath, claim))
+        return false;
+    let removed = false;
+    try {
+        const current = readLockBlob(lockPath);
+        if (current
+            && current.mutation_id === observed.mutation_id
+            && lockIsStale(current, Date.now())) {
+            fs.unlinkSync(lockPath);
+            removed = true;
+        }
+        return removed;
+    }
+    finally {
+        // Delete only our own claim. A crash before this point intentionally leaves
+        // a fail-closed marker instead of guessing that a different process is dead.
+        try {
+            const currentClaim = readLockBlob(claimPath);
+            if (currentClaim?.mutation_id === claim.mutation_id)
+                fs.unlinkSync(claimPath);
+        }
+        catch {
+            /* best-effort; a retained claim fails closed for this stale generation */
+        }
+    }
 }
 function acquireRaw(lockPath, blob) {
     ensureDirFor(lockPath);
@@ -221,10 +279,10 @@ export function acquireLock(options) {
         if (existing) {
             if (lockIsStale(existing, Date.now())) {
                 try {
-                    fs.unlinkSync(options.lockPath);
+                    reapObservedLock(options.lockPath, existing, options.agentId);
                 }
                 catch {
-                    /* race with another reaper; retry */
+                    /* another reaper won or I/O failed; exclusive acquire below retries */
                 }
             }
         }