brainclaw 1.5.5 → 1.6.0

package/dist/core/agentrun-reconciler.js

@@ -50,6 +50,8 @@ export const DEFAULT_HEALTH_CHECK_GRACE_MS = 60_000;
  * declared `failed` with `silent_termination_no_evidence`. Default 30 min.
  */
 export const DEFAULT_STALE_AFTER_MS = 30 * 60_000;
+export const DEFAULT_DEAD_PID_READ_SWEEP_AGE_MS = 5 * 60_000;
+export const DEFAULT_DEAD_PID_READ_SWEEP_LIMIT = 50;
 const TERMINAL_STATUSES = new Set([
     'completed', 'failed', 'cancelled', 'timed_out', 'interrupted',
 ]);
@@ -309,6 +311,69 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
         evidence, previous_status, current_status: run.status,
     };
 }
+export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {}) {
+    const run = loadAgentRun(runId, cwd);
+    if (!run) {
+        const evidence = {
+            age_ms: 0, has_post_start_commit: false, claim_released: false,
+            assignment_completed: false, process_alive: undefined,
+        };
+        return {
+            run_id: runId, action: 'no_op', reason: 'run not found', evidence,
+            previous_status: 'created', current_status: 'created',
+        };
+    }
+    const evidence = collectEvidence(run, cwd, { nowMs: options.nowMs });
+    if (run.status !== 'running') {
+        return {
+            run_id: run.id, action: 'no_op', reason: `run status is ${run.status}, not running`,
+            evidence, previous_status: run.status, current_status: run.status,
+        };
+    }
+    if (evidence.process_alive !== false) {
+        return {
+            run_id: run.id, action: 'no_op',
+            reason: evidence.process_alive === true ? 'process alive' : 'pid liveness unknown',
+            evidence, previous_status: run.status, current_status: run.status,
+        };
+    }
+    try {
+        transitionAgentRun(run.id, 'cancelled', {
+            actor: options.actor ?? 'reconciler',
+            status_reason: 'pid_dead_at_read',
+        }, cwd);
+        return {
+            run_id: run.id, action: 'cancelled_dead_pid', reason: 'pid_dead_at_read',
+            evidence, previous_status: run.status, current_status: 'cancelled',
+        };
+    }
+    catch (err) {
+        return {
+            run_id: run.id, action: 'no_op',
+            reason: `cancel transition rejected: ${err instanceof Error ? err.message : String(err)}`,
+            evidence, previous_status: run.status, current_status: run.status,
+        };
+    }
+}
+export function sweepDeadPidRunningAgentRunsAtRead(cwd, options = {}) {
+    const now = options.nowMs ?? Date.now();
+    const minAgeMs = options.staleAfterMs ?? DEFAULT_DEAD_PID_READ_SWEEP_AGE_MS;
+    const cutoff = now - minAgeMs;
+    const limit = options.limit ?? DEFAULT_DEAD_PID_READ_SWEEP_LIMIT;
+    const candidates = listAgentRuns(cwd, { status: 'running' })
+        .filter((run) => {
+        const lastEventAt = run.last_event_at ?? run.started_at ?? run.created_at;
+        const ts = new Date(lastEventAt).getTime();
+        return Number.isFinite(ts) && ts <= cutoff;
+    })
+        .sort((left, right) => {
+        const leftTs = new Date(left.last_event_at ?? left.started_at ?? left.created_at).getTime();
+        const rightTs = new Date(right.last_event_at ?? right.started_at ?? right.created_at).getTime();
+        return rightTs - leftTs;
+    })
+        .slice(0, limit);
+    return candidates.map((run) => reconcileDeadPidRunningAgentRunAtRead(run.id, cwd, options));
+}
 /**
  * Reconcile every non-terminal agent_run matching `filter`. Useful for
  * batch sweeps from `bclaw_assignment_events` or `brainclaw doctor --dispatch`.

package/dist/core/claims.js

@@ -59,6 +59,35 @@ export function saveClaim(claim, cwd) {
         catch { /* best-effort */ }
     });
 }
+/**
+ * Atomically check for an active claim on `scope` and save a new one if absent.
+ *
+ * Atomicity is provided by running both operations inside a single mutate() call;
+ * the mutation-pipeline mutex serializes filesystem writes on the claims store.
+ */
+export function acquireClaimScope(input, cwd) {
+    return mutate({ cwd }, () => {
+        const conflictingClaim = listClaims(cwd).find((claim) => claim.status === 'active' && claim.scope === input.scope);
+        if (conflictingClaim) {
+            return { acquired: false, conflicting_claim: conflictingClaim };
+        }
+        const claim = {
+            id: generateClaimId(),
+            agent: input.agent,
+            agent_id: input.agent_id,
+            user: input.user,
+            session_id: input.session_id,
+            scope: input.scope,
+            description: input.description,
+            created_at: nowISO(),
+            status: 'active',
+            plan_id: input.plan_id,
+            model: input.model,
+        };
+        saveClaim(claim, cwd);
+        return { acquired: true, claim };
+    });
+}
 export function loadClaim(id, cwd) {
     return claimStore(cwd).load(id);
 }

package/dist/core/dispatch-status.js

@@ -0,0 +1,219 @@
+/**
+ * Consolidated dispatch status (pln#503 phase 3.1).
+ *
+ * Resolves a single dispatch reference (`asgn_…`, `clm_…`, `lop_…`, `run_…`)
+ * into the full set of linked entities — assignment, claim, loop, agent_run —
+ * plus on-disk artefacts (brief-ack sentinel, stdout/stderr logs) and a
+ * pid-liveness check, then computes a health verdict + a recommended next
+ * action for the caller.
+ *
+ * The motivating use case: an agent who just called `bclaw_coordinate` and
+ * got `execution_status: "delivered_and_started"` should be able to verify
+ * the dispatch is alive without running five separate `bclaw_find` calls.
+ * The `verify_with` hint added in phase 3.3 already points callers at this
+ * tool by name.
+ *
+ * See docs/concepts/dispatch-lifecycle.md for the full entity-relationship
+ * and FSM model.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadAssignment, listAssignments } from './assignments.js';
+import { loadAgentRun, listAgentRuns } from './agentruns.js';
+import { loadClaim } from './claims.js';
+import { getLoop, listLoops } from './loops/store.js';
+import { isProcessAlive } from './agentrun-reconciler.js';
+const DEFAULT_TAIL = 20;
+const DEFAULT_STALL_MS = 5 * 60_000;
+// ── Internal helpers ──────────────────────────────────────────────────────
+function readLogTail(filePath, lines) {
+    try {
+        const stat = fs.statSync(filePath);
+        if (lines <= 0) {
+            return { path: filePath, exists: true, size_bytes: stat.size };
+        }
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const all = content.split(/\r?\n/);
+        // Strip trailing empty line from final \n
+        if (all.length > 0 && all[all.length - 1] === '')
+            all.pop();
+        return {
+            path: filePath,
+            exists: true,
+            size_bytes: stat.size,
+            tail: all.slice(-lines),
+        };
+    }
+    catch {
+        return { path: filePath, exists: false, size_bytes: 0 };
+    }
+}
+function findLoopByAssignmentId(assignmentId, cwd) {
+    for (const loop of listLoops({}, cwd)) {
+        if (loop.slots.some((s) => s.assignment_id === assignmentId))
+            return loop;
+    }
+    return undefined;
+}
+function resolveTarget(targetId, cwd) {
+    if (targetId.startsWith('asgn_')) {
+        return { resolved_from: 'assignment_id', assignment_id: targetId };
+    }
+    if (targetId.startsWith('run_')) {
+        const run = loadAgentRun(targetId, cwd);
+        if (run)
+            return { resolved_from: 'run_id', assignment_id: run.assignment_id, agent_run: run };
+        return { resolved_from: 'unresolved' };
+    }
+    if (targetId.startsWith('clm_')) {
+        const assignments = listAssignments(cwd, { claim_id: targetId });
+        if (assignments.length > 0) {
+            // Pick the most recent assignment for this claim (latest created_at).
+            const recent = [...assignments].sort((a, b) => b.created_at.localeCompare(a.created_at))[0];
+            return { resolved_from: 'claim_id', assignment_id: recent.id };
+        }
+        return { resolved_from: 'claim_id' };
+    }
+    if (targetId.startsWith('lop_')) {
+        const loop = getLoop(targetId, cwd);
+        if (loop) {
+            // Prefer the slot in the current_phase with an assignment_id; fall back
+            // to any slot's assignment_id.
+            const phaseSlot = loop.slots.find((s) => s.phase === loop.current_phase && s.assignment_id);
+            const anySlot = loop.slots.find((s) => s.assignment_id);
+            const slot = phaseSlot ?? anySlot;
+            if (slot?.assignment_id) {
+                return { resolved_from: 'loop_id', assignment_id: slot.assignment_id };
+            }
+            return { resolved_from: 'loop_id' };
+        }
+        return { resolved_from: 'unresolved' };
+    }
+    return { resolved_from: 'unresolved' };
+}
+const TERMINAL_RUN_STATUSES = new Set([
+    'completed', 'failed', 'cancelled', 'timed_out', 'interrupted',
+]);
+function computeDiagnosis(assignment, agentRun, runtime, options) {
+    if (!assignment && !agentRun) {
+        return {
+            health: 'unknown',
+            summary: 'target_id did not resolve to any assignment or agent_run',
+            recommended_next_action: 'Verify the target_id is correct (asgn_/clm_/lop_/run_). Use bclaw_find(entity="assignment") to list available assignments.',
+        };
+    }
+    if (!agentRun) {
+        return {
+            health: 'not_dispatched',
+            summary: `assignment exists (status=${assignment?.status}) but no agent_run record — the spawn never produced a process, or the assignment is still waiting to be picked up`,
+            recommended_next_action: assignment?.status === 'offered'
+                ? 'Wait for the target agent to accept, or reroute via bclaw_coordinate(intent="reroute", scope=…).'
+                : 'Re-dispatch with bclaw_coordinate or check for an earlier spawn error.',
+        };
+    }
+    if (TERMINAL_RUN_STATUSES.has(agentRun.status)) {
+        const isSuccess = agentRun.status === 'completed';
+        return {
+            health: 'terminal',
+            summary: `agent_run already terminal (status=${agentRun.status})${agentRun.status_reason ? `: ${agentRun.status_reason}` : ''}`,
+            recommended_next_action: isSuccess
+                ? 'Harvest artifacts and move on; if the assignment is still open, transition it to completed.'
+                : 'Read stderr log (path in runtime.log_files.stderr) for the failure detail; reroute or retry if appropriate.',
+        };
+    }
+    // status is running / launching / waiting_input / blocked → check liveness
+    const lastEventMs = new Date(agentRun.last_event_at ?? agentRun.started_at ?? agentRun.created_at).getTime();
+    const stallAge = options.nowMs - lastEventMs;
+    if (runtime.pid_alive === false) {
+        return {
+            health: 'silent_death',
+            summary: `agent_run.status="${agentRun.status}" but pid ${runtime.pid} is dead — worker exited without self-reporting; lazy reconciler will mark it failed after the stale window (default 30min)`,
+            recommended_next_action: 'Read .stderr.log for the exit reason; then trigger reconciliation by calling bclaw_find(entity="agent_run") again, or cancel + reroute.',
+        };
+    }
+    if (runtime.pid_alive === true && stallAge > options.stallMs) {
+        return {
+            health: 'stalled',
+            summary: `agent_run alive (pid=${runtime.pid}) but no activity for ${Math.round(stallAge / 1000)}s; last_event_at=${agentRun.last_event_at ?? '(never)'}`,
+            recommended_next_action: 'Tail the stdout/stderr log to see whether the worker is doing useful work; if truly hung, kill the pid and reroute.',
+        };
+    }
+    if (runtime.pid_alive === true) {
+        return {
+            health: 'healthy',
+            summary: `agent_run.status="${agentRun.status}", pid ${runtime.pid} alive, last activity ${Math.round(stallAge / 1000)}s ago`,
+            recommended_next_action: 'No action — the dispatch is alive and recent. Re-check periodically until terminal.',
+        };
+    }
+    // pid_alive undefined → cannot determine (no pid tracked, or signal failed)
+    return {
+        health: 'unknown',
+        summary: `agent_run.status="${agentRun.status}" but pid liveness could not be determined (pid=${agentRun.pid ?? '(none)'})`,
+        recommended_next_action: 'Read the stdout/stderr log for life signs; or wait for the lazy reconciler to converge based on commit / claim / assignment evidence.',
+    };
+}
+// ── Public API ─────────────────────────────────────────────────────────────
+export function getDispatchStatus(options) {
+    const cwd = options.cwd;
+    const tailLines = options.tail_log_lines ?? DEFAULT_TAIL;
+    const stallMs = options.stall_threshold_ms ?? DEFAULT_STALL_MS;
+    const nowMs = options.nowMs ?? Date.now();
+    const resolved = resolveTarget(options.target_id, cwd);
+    const assignmentId = resolved.assignment_id;
+    const assignment = assignmentId ? loadAssignment(assignmentId, cwd) : undefined;
+    const claim = assignment?.claim_id ? loadClaim(assignment.claim_id, cwd) : undefined;
+    // Prefer the pre-resolved agent_run (when target_id was a run_…); otherwise
+    // look up by assignment_id and pick the most recent attempt.
+    let agentRun = resolved.agent_run;
+    if (!agentRun && assignmentId) {
+        const runs = listAgentRuns(cwd, { assignment_id: assignmentId });
+        agentRun = [...runs].sort((a, b) => b.created_at.localeCompare(a.created_at))[0];
+    }
+    let loop;
+    if (resolved.resolved_from === 'loop_id') {
+        loop = getLoop(options.target_id, cwd);
+    }
+    else if (assignmentId) {
+        loop = findLoopByAssignmentId(assignmentId, cwd);
+    }
+    // Runtime artefacts (ack file + log files) — all under the project's
+    // coordination root. Use the cwd or the runtime cwd as the anchor; the
+    // dispatcher writes them under cwd/.brainclaw/coordination/runtime/...
+    const projectRoot = cwd ?? process.cwd();
+    const runtimeRoot = path.join(projectRoot, '.brainclaw', 'coordination', 'runtime');
+    const ackPath = assignmentId ? path.join(runtimeRoot, 'ack', `${assignmentId}.ack`) : undefined;
+    const stdoutPath = assignmentId ? path.join(runtimeRoot, 'log', `${assignmentId}.stdout.log`) : undefined;
+    const stderrPath = assignmentId ? path.join(runtimeRoot, 'log', `${assignmentId}.stderr.log`) : undefined;
+    const runtime = {
+        pid: agentRun?.pid,
+        pid_alive: isProcessAlive(agentRun?.pid),
+        ack_file: {
+            exists: ackPath ? fs.existsSync(ackPath) : false,
+            path: ackPath,
+        },
+        log_files: {
+            stdout: stdoutPath ? readLogTail(stdoutPath, tailLines) : undefined,
+            stderr: stderrPath ? readLogTail(stderrPath, tailLines) : undefined,
+        },
+    };
+    const diagnosis = computeDiagnosis(assignment, agentRun, runtime, { stallMs, nowMs });
+    return {
+        target_id: options.target_id,
+        resolved_from: resolved.resolved_from,
+        entities: {
+            assignment_id: assignmentId,
+            claim_id: assignment?.claim_id,
+            loop_id: loop?.id,
+            run_id: agentRun?.id,
+        },
+        assignment,
+        claim,
+        loop,
+        agent_run: agentRun,
+        runtime,
+        diagnosis,
+    };
+}
+//# sourceMappingURL=dispatch-status.js.map

package/dist/core/entity-operations.js

@@ -19,12 +19,14 @@ import { listClaims } from './claims.js';
 import { listActionRequired } from './actions.js';
 import { deleteAssignment, listAssignments, loadAssignment, saveAssignment, transitionAssignment } from './assignments.js';
 import { listAgentRuns } from './agentruns.js';
+import { reconcileAgentRun, reconcileDeadPidRunningAgentRunAtRead, TERMINAL_STATUSES } from './agentrun-reconciler.js';
 import { deleteRuntimeNote, listRuntimeNotes, saveRuntimeNote, } from './runtime.js';
 import { createConstraint, createDecision, createTrap, } from './operations/memory-write.js';
 import { deleteMemoryItem, findMemoryItemInChain, updateMemoryItem, } from './operations/memory-mutation.js';
 import { createPlan, deletePlan, updatePlan, } from './operations/plan.js';
 import { ENTITY_REGISTRY, isValidTransition, } from './entity-registry.js';
 import { generateId } from './ids.js';
+import { CandidateTypeSchema, ConstraintCategorySchema, DecisionOutcomeSchema, MemoryVisibilitySchema, PlanTypeEnumSchema, PrioritySchema, RuntimeNoteTypeSchema, SeveritySchema, } from './schema.js';
 /**
  * Default provenance stamp applied on create when the caller does not
  * supply one. `user` kind with whatever author is in the payload; the
@@ -79,6 +81,44 @@ export class InvalidTransitionError extends Error {
     }
 }
 // ─── FIND ─────────────────────────────────────────────────────────────
+/**
+ * Lazy reconciliation pass on agent_run reads (pln#503 phase 3.2).
+ *
+ * Before returning agent_run records to `bclaw_find` / `bclaw_get`, walk any
+ * record whose status is non-terminal and call `reconcileAgentRun(id)`. The
+ * reconciler:
+ *   - no-ops for runs under the 60s grace window or already terminal
+ *   - transitions to `completed` (inferred=true) when evidence of completion
+ *     exists (post-start commit, claim released, assignment completed)
+ *   - transitions to `failed` (silent_termination_no_evidence) when the run
+ *     is past the stale threshold AND its pid is provably dead
+ *
+ * Without this pass, a worker that crashed before its first output keeps
+ * `status="running"` indefinitely — the empirical pattern recorded in trp#292.
+ * The full agentrun-reconciler.ts machinery already existed (pln#496); this
+ * just wires it into the canonical-grammar read path so every read of
+ * `agent_run` produces converged state.
+ */
+function loadAgentRunsWithReconciliation(cwd) {
+    const runs = listAgentRuns(cwd);
+    for (const run of runs) {
+        if (run.status === 'running') {
+            try {
+                reconcileDeadPidRunningAgentRunAtRead(run.id, cwd);
+            }
+            catch { /* best-effort: never block reads on reconciliation errors */ }
+            continue;
+        }
+        if (!TERMINAL_STATUSES.has(run.status)) {
+            try {
+                reconcileAgentRun(run.id, cwd);
+            }
+            catch { /* best-effort: never block reads on reconciliation errors */ }
+        }
+    }
+    // Re-list to capture any transitions made above.
+    return listAgentRuns(cwd);
+}
 export function listEntities(name, cwd, filter = {}) {
     const all = loadAll(name, cwd);
     const filtered = applyFilter(all, filter);
@@ -97,7 +137,7 @@ function loadAll(name, cwd) {
         case 'claim': return listClaims(cwd);
         case 'action': return listActionRequired(cwd);
         case 'assignment': return listAssignments(cwd);
-        case 'agent_run': return listAgentRuns(cwd);
+        case 'agent_run': return loadAgentRunsWithReconciliation(cwd);
         case 'cross_project_link': return resolveCrossProjectLinks(cwd);
         default:
             throw new EntityOperationUnsupportedError(name, 'find');
@@ -112,12 +152,24 @@ function applyFilter(items, filter) {
     if (filter.tag) {
         result = result.filter((item) => Array.isArray(item.tags) && item.tags.includes(filter.tag));
     }
+    if (Array.isArray(filter.tags) && filter.tags.length > 0) {
+        result = result.filter((item) => Array.isArray(item.tags) && filter.tags.some((tag) => item.tags.includes(tag)));
+    }
     if (filter.author) {
         result = result.filter((item) => item.author === filter.author);
     }
     if (filter.plan_id) {
         result = result.filter((item) => item.plan_id === filter.plan_id);
     }
+    if (filter.assignment_id) {
+        result = result.filter((item) => item.assignment_id === filter.assignment_id);
+    }
+    if (filter.claim_id) {
+        result = result.filter((item) => item.claim_id === filter.claim_id);
+    }
+    if (filter.message_id) {
+        result = result.filter((item) => item.message_id === filter.message_id);
+    }
     if (filter.source) {
         result = result.filter((item) => item.source === filter.source);
     }
@@ -166,8 +218,8 @@ export function createEntity(name, data, cwd) {
             const res = createPlan({
                 text: requireString(data, 'text'),
                 author: requireString(data, 'author'),
-                type: data.type,
-                priority: data.priority,
+                type: requireEnum(data, 'type', PlanTypeEnumSchema.options, { optional: true }),
+                priority: requireEnum(data, 'priority', PrioritySchema.options, { optional: true }),
                 assignee: data.assignee,
                 project: data.project,
                 tags: data.tags,
@@ -182,7 +234,7 @@ export function createEntity(name, data, cwd) {
             const res = createDecision({
                 text: requireString(data, 'text'),
                 author: requireString(data, 'author'),
-                outcome: data.outcome,
+                outcome: requireEnum(data, 'outcome', DecisionOutcomeSchema.options, { optional: true }),
                 tags: data.tags,
                 relatedPaths: data.related_paths,
                 planId: data.plan_id,
@@ -194,7 +246,7 @@ export function createEntity(name, data, cwd) {
             const res = createConstraint({
                 text: requireString(data, 'text'),
                 author: requireString(data, 'author'),
-                category: data.category,
+                category: requireEnum(data, 'category', ConstraintCategorySchema.options, { optional: true }),
                 tags: data.tags,
                 relatedPaths: data.related_paths,
             }, cwd);
@@ -205,7 +257,7 @@ export function createEntity(name, data, cwd) {
             const res = createTrap({
                 text: requireString(data, 'text'),
                 author: requireString(data, 'author'),
-                severity: (data.severity ?? 'medium'),
+                severity: requireEnum(data, 'severity', SeveritySchema.options, { optional: true }) ?? 'medium',
                 tags: data.tags,
                 relatedPaths: data.related_paths,
             }, cwd);
@@ -220,8 +272,8 @@ export function createEntity(name, data, cwd) {
                 text: requireString(data, 'text'),
                 created_at: new Date().toISOString(),
                 tags: data.tags ?? [],
-                visibility: data.visibility ?? 'shared',
-                note_type: data.note_type ?? 'observation',
+                visibility: requireEnum(data, 'visibility', MemoryVisibilitySchema.options, { optional: true }) ?? 'shared',
+                note_type: requireEnum(data, 'note_type', RuntimeNoteTypeSchema.options, { optional: true }) ?? 'observation',
                 provenance: defaultProvenance(data),
                 ...(data.agent_id ? { agent_id: data.agent_id } : {}),
                 ...(data.project_id ? { project_id: data.project_id } : {}),
@@ -233,9 +285,15 @@ export function createEntity(name, data, cwd) {
         }
         case 'candidate': {
             const id = generateId('candidate');
+            const validatedType = requireEnum(data, 'type', CandidateTypeSchema.options);
+            if (!validatedType) {
+                // requireEnum without `optional` throws on missing/invalid, but
+                // narrow the type for the assignment below.
+                throw new Error(`Missing required field: type`);
+            }
             const candidate = {
                 id,
-                type: requireString(data, 'type'),
+                type: validatedType,
                 text: requireString(data, 'text'),
                 created_at: new Date().toISOString(),
                 author: requireString(data, 'author'),
@@ -281,6 +339,9 @@ export function updateEntity(name, id, patch, cwd) {
             // declared updatable fields (text, tags, estimated_effort, depends_on)
             // actually land. The typed surface still covers status/assignee/priority/
             // actualEffort for legacy CLI callers — see UpdatePlanInput.
+            // Note: `plan.type` is intentionally create-only (not in plan.updatable
+            // at entity-registry.ts) — no validation needed here.
+            validatePatchEnum(patch, 'priority', PrioritySchema.options);
             updatePlan({
                 id,
                 patch: patch,
@@ -293,6 +354,15 @@ export function updateEntity(name, id, patch, cwd) {
             // Same generic-patch escape-hatch for memory items. Registry declares
             // severity, scope, related_paths, expires_at, etc. as updatable; the
             // legacy explicit text/tags whitelist silently dropped them.
+            if (name === 'decision') {
+                validatePatchEnum(patch, 'outcome', DecisionOutcomeSchema.options);
+            }
+            else if (name === 'constraint') {
+                validatePatchEnum(patch, 'category', ConstraintCategorySchema.options);
+            }
+            else {
+                validatePatchEnum(patch, 'severity', SeveritySchema.options);
+            }
             updateMemoryItem({
                 id,
                 type: name,
@@ -301,6 +371,9 @@ export function updateEntity(name, id, patch, cwd) {
             return { entity: name, id };
         }
         case 'runtime_note': {
+            // Note: `note_type` is intentionally create-only (not in
+            // runtime_note.updatable at entity-registry.ts) — no validation needed.
+            validatePatchEnum(patch, 'visibility', MemoryVisibilitySchema.options);
             const notes = listRuntimeNotes(undefined, cwd);
             const note = notes.find((n) => n.id === id);
             if (!note)
@@ -318,6 +391,8 @@ export function updateEntity(name, id, patch, cwd) {
             return { entity: name, id };
         }
         case 'candidate': {
+            // Note: `candidate.type` is intentionally create-only (not in
+            // candidate.updatable at entity-registry.ts) — no validation needed.
             const candidate = loadCandidate(id, cwd);
             const patched = { ...candidate, ...patch };
             saveCandidate(patched, cwd);
@@ -484,4 +559,48 @@ function requireString(data, field) {
     }
     return value;
 }
+/**
+ * Validates that data[field] is one of `validValues`, throwing a clear
+ * error message when the value is invalid. Fixes the silent-data-loss bug
+ * documented in candidate can_a3458961 + pln#509 step 1: previously the
+ * create path used unchecked `as` casts on enum fields, so invalid values
+ * (e.g. outcome:'accepted' instead of 'approved') were written to disk and
+ * then silently skipped at load time by the strict Zod parser. Now we
+ * validate at write time against the same valid-value lists used by the
+ * load-time schemas.
+ *
+ * Callers pass `XxxSchema.options` (a readonly tuple of valid strings)
+ * rather than the schema itself — this avoids brittle generic constraints
+ * on Zod's enum type which differs between major versions.
+ */
+function requireEnum(data, field, validValues, opts = {}) {
+    const value = data[field];
+    if (value === undefined || value === null) {
+        if (opts.optional)
+            return undefined;
+        throw new Error(`Missing required field: ${field}`);
+    }
+    if (typeof value !== 'string' || !validValues.includes(value)) {
+        throw new Error(`Invalid value for '${field}': got ${JSON.stringify(value)}. Expected one of: ${validValues.join(' | ')}`);
+    }
+    return value;
+}
+/**
+ * Validates that, if `patch[field]` is present (and not null/undefined), it
+ * matches one of `validValues`. Used by updateEntity for enum-shaped patch
+ * fields, to extend the same validation parity used at create time. Codex
+ * round 1 (pln#509 step 1 review) correctly flagged that updateEntity was
+ * still vulnerable to the same silent persistence bug when patching enum
+ * fields with invalid values. Fields not present in `patch` are ignored.
+ */
+function validatePatchEnum(patch, field, validValues) {
+    if (!(field in patch))
+        return;
+    const value = patch[field];
+    if (value === undefined || value === null)
+        return;
+    if (typeof value !== 'string' || !validValues.includes(value)) {
+        throw new Error(`Invalid value for '${field}' in patch: got ${JSON.stringify(value)}. Expected one of: ${validValues.join(' | ')}`);
+    }
+}
 //# sourceMappingURL=entity-operations.js.map

package/dist/core/execution-adapters.js

@@ -90,14 +90,38 @@ export class CliExecutionAdapter {
         const spawnExecutable = resolvedExecutable ?? invoke.executable;
         const useShell = isWin32 && /\.(cmd|bat)$/i.test(spawnExecutable);
         const needsStdin = invoke.promptDelivery === 'stdin_pipe' && invoke.promptText;
-        const stdio = needsStdin ? ['pipe', 'ignore', 'ignore'] : 'ignore';
+        // pln#504: open per-assignment log files for stdout/stderr capture so silent
+        // worker deaths (trp#292) become diagnosable. Previously stdio used 'ignore'
+        // for stdout+stderr — anything the worker said vanished. Best-effort: on
+        // failure to open log files we fall back to the legacy 'ignore' behaviour
+        // rather than abort the spawn.
+        const useAckWrap = !!(options.assignmentId && (options.ackRoot ?? options.worktreePath));
+        let logFds;
+        if (useAckWrap) {
+            try {
+                const logRoot = options.ackRoot ?? options.worktreePath;
+                const logDir = path.join(logRoot, '.brainclaw', 'coordination', 'runtime', 'log');
+                fs.mkdirSync(logDir, { recursive: true });
+                logFds = {
+                    stdout: fs.openSync(path.join(logDir, `${options.assignmentId}.stdout.log`), 'a'),
+                    stderr: fs.openSync(path.join(logDir, `${options.assignmentId}.stderr.log`), 'a'),
+                };
+            }
+            catch {
+                // Log capture is best-effort — never block the spawn on logging issues.
+                logFds = undefined;
+            }
+        }
+        const stdinTarget = needsStdin ? 'pipe' : 'ignore';
+        const stdoutTarget = logFds ? logFds.stdout : 'ignore';
+        const stderrTarget = logFds ? logFds.stderr : 'ignore';
+        const stdio = [stdinTarget, stdoutTarget, stderrTarget];
         // pln#476: wrap the spawn command with a brief-ack step so the worker
         // shell touches a sentinel file BEFORE the agent binary runs.
         // waitForAssignmentHandshake checks that file as evidence the spawn
         // executed — needed for codex (which lacks the brainclaw MCP context
         // to call bclaw_assignment_update). When ackRoot/assignmentId are
         // omitted, we keep the original direct-binary spawn.
-        const useAckWrap = !!(options.assignmentId && (options.ackRoot ?? options.worktreePath));
         let child;
         if (useAckWrap) {
             const ackRoot = options.ackRoot ?? options.worktreePath;
@@ -139,6 +163,18 @@ export class CliExecutionAdapter {
             child.stdin.end();
         }
         child.unref();
+        // Close the parent's copies of the log file descriptors. The child has its
+        // own dup'd copies and will keep writing to them after we return.
+        if (logFds) {
+            try {
+                fs.closeSync(logFds.stdout);
+            }
+            catch { /* best-effort */ }
+            try {
+                fs.closeSync(logFds.stderr);
+            }
+            catch { /* best-effort */ }
+        }
         const pid = child.pid;
         if (!pid) {
             throw new Error(`Failed to spawn agent ${options.agent}: no PID returned`);