brainclaw 1.5.5 → 1.7.0

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`);

package/dist/core/facade-schema.js

@@ -13,6 +13,7 @@ export const WorkRequestSchema = z.object({
     task: z.string().optional(),
     messageId: z.string().optional(),
     contextTarget: z.string().optional(),
+    project: z.string().optional(),
     compact: z.boolean().optional().default(true),
 });
 export const CoordinateRequestSchema = z.object({
@@ -54,6 +55,43 @@ export const CoordinateRequestSchema = z.object({
      * the target agent picks up the brief async via its own bclaw_work.
      */
     project: z.string().optional(),
+    /**
+     * Bypass the pre-flight uncommitted-changes check (can_30c295b4 fix).
+     * By default, bclaw_coordinate refuses dispatches when the source cwd
+     * has uncommitted modifications, because the dispatched worker spawns
+     * from HEAD and won't see them — leading to silent review on stale code.
+     * Set allow_dirty=true to override (e.g. when the caller knows the
+     * dispatched work doesn't depend on the dirty files, or when running
+     * tests). Has no effect when the source cwd is not a git repo.
+     */
+    allow_dirty: z.preprocess(
+    // MCP clients that don't know allow_dirty is a boolean (it was previously
+    // absent from the published inputSchema) send the string "true"/"false".
+    // Coerce those so the documented escape hatch actually works; leave real
+    // booleans and undefined untouched.
+    (value) => (typeof value === 'string' ? value.trim().toLowerCase() === 'true' : value), z.boolean().optional()),
+    /**
+     * pln#520 Tier 2 (P2c) — explicit git ref (commit / branch / tag) the
+     * dispatched worker should build its worktree from, instead of the default
+     * HEAD. When set on a worktree-creating intent (assign / review / reroute),
+     * the worktree is checked out at this ref, so uncommitted working-tree
+     * changes in the source are intentionally out of scope and the scope-aware
+     * dirty guard allows the dispatch. Passed through to
+     * createCoordinatorClaim's worktreeBaseRef. Ignored by intents that don't
+     * create a worktree (consult / ideate / summarize).
+     */
+    ref: z.string().min(1).optional(),
+    /**
+     * pln#511 step 2 — loop preset selector. When set on intent='ideate',
+     * the handler bypasses the kind-default ideation phases and opens the
+     * loop with the named preset's phases / stop_condition / protocol.
+     * v1 ships a single preset ('bootstrap', see src/core/loops/presets/).
+     * The handler validates the name against the preset registry and
+     * rejects unknown names with `unknown_preset`. Presets are kind-
+     * specific: passing `preset` with any intent other than 'ideate' is
+     * rejected as `preset_kind_mismatch`.
+     */
+    preset: z.string().min(1).optional(),
 });
 export const FacadeArtifactSchema = z.object({
     type: z.string(),
@@ -65,6 +103,21 @@ export const FacadeSideEffectSchema = z.object({
     entity: z.string(),
     id: z.string(),
 });
+/**
+ * Self-documenting verification hint attached to dispatch responses (pln#503
+ * phase 3.3). Tells the caller exactly which canonical-grammar call to make
+ * next to verify the spawn is actually doing work — `delivered_and_started`
+ * is a brief-ack signal, not proof of life. See dispatch-lifecycle.md.
+ */
+export const VerifyWithSchema = z.object({
+    action: z.literal('bclaw_find'),
+    entity: z.literal('agent_run'),
+    filter: z.object({ assignment_id: z.string() }),
+    /** Human-readable description of what to look for in the result. */
+    expected_when_alive: z.string(),
+    /** Doc pointer for the diagnostic flow when the check fails. */
+    see_also: z.string(),
+});
 export const FacadeResponseSchema = z.object({
     status: z.enum(['ok', 'error', 'partial']),
     intent: z.string(),
@@ -77,5 +130,23 @@ export const FacadeResponseSchema = z.object({
     session_id: z.string().optional(),
     warnings: z.array(z.string()),
     execution_status: ExecutionStatusSchema.optional(),
+    /** pln#503 phase 3.3: present when execution_status === 'delivered_and_started'. */
+    verify_with: VerifyWithSchema.optional(),
+    /**
+     * pln#513 step 1 — bclaw_work hint surfaced when the project lacks a usable
+     * PROJECT.md (absent or zero bytes). True means the agent should consider
+     * opening a bootstrap loop before assuming context; the literal call to
+     * make is in `next_action`. False or absent means the project already has
+     * a PROJECT.md and the bootstrap entry-point should not be offered.
+     * Additive: existing callers that don't read it are unaffected.
+     */
+    bootstrap_recommended: z.boolean().optional(),
+    /**
+     * pln#513 step 1 — literal MCP call to surface as the bootstrap entry-point
+     * when `bootstrap_recommended` is true. Carries the canonical-grammar text
+     * (`bclaw_coordinate(intent='ideate', preset='bootstrap')`) verbatim so the
+     * CLI doesn't have to reconstruct it.
+     */
+    next_action: z.string().optional(),
 });
 //# sourceMappingURL=facade-schema.js.map

package/dist/core/federation-cloud.js

@@ -2,24 +2,29 @@ import { loadConfig } from './config.js';
 import { logger } from './logger.js';
 const DEFAULT_API_URL = 'https://app.brainclaw.dev';
 function resolveCloudConfig(cwd) {
-    // Check env vars first
-    const apiUrl = process.env.BRAINCLAW_CLOUD_URL ?? DEFAULT_API_URL;
-    const apiKey = process.env.BRAINCLAW_CLOUD_API_KEY;
-    if (apiKey) {
-        return { apiUrl, apiKey };
-    }
-    // Check config.yaml
+    const envApiUrl = process.env.BRAINCLAW_CLOUD_URL;
+    const envApiKey = process.env.BRAINCLAW_CLOUD_API_KEY;
+    let configEnabled = false;
+    let configEndpoint;
+    let configApiKey;
     try {
         const config = loadConfig(cwd);
-        const cloud = config.cloud;
-        if (cloud?.api_key) {
-            return { apiUrl: cloud.api_url ?? apiUrl, apiKey: cloud.api_key };
+        if (config.cloud_sync) {
+            configEnabled = config.cloud_sync.enabled === true;
+            configEndpoint = config.cloud_sync.endpoint;
+            configApiKey = config.cloud_sync.api_key;
         }
     }
     catch {
-        // No config — cloud not configured
+        // No config available — fall back to env only
     }
-    return undefined;
+    const apiKey = envApiKey ?? configApiKey;
+    if (!apiKey)
+        return undefined;
+    // Env-supplied key implies explicit opt-in; config flag is the alternative
+    const enabled = Boolean(envApiKey) || configEnabled;
+    const apiUrl = envApiUrl ?? configEndpoint ?? DEFAULT_API_URL;
+    return { apiUrl, apiKey, enabled };
 }
 export async function pushSignalToCloud(message, cwd) {
     const cloud = resolveCloudConfig(cwd);
@@ -96,4 +101,14 @@ export async function pushBoardToCloud(projectName, boardData, cwd) {
 export function isCloudConfigured(cwd) {
     return resolveCloudConfig(cwd) !== undefined;
 }
+/**
+ * Returns true when cloud sync is both configured AND explicitly opted-in.
+ * Use this gate for automatic lifecycle hooks (session-start pull, session-end push).
+ * `isCloudConfigured` alone does NOT imply opt-in — a stale config api_key without
+ * `cloud_sync.enabled=true` and without the BRAINCLAW_CLOUD_API_KEY env var stays inert.
+ */
+export function isCloudSyncEnabled(cwd) {
+    const cloud = resolveCloudConfig(cwd);
+    return cloud !== undefined && cloud.enabled;
+}
 //# sourceMappingURL=federation-cloud.js.map

package/dist/core/federation-materialize.js

@@ -0,0 +1,57 @@
+import { CandidateSchema, HandoffSchema, RuntimeNoteSchema } from './schema.js';
+import { saveCandidate, generateCandidateIdWithLabel } from './candidates.js';
+import { saveRuntimeNote, generateRuntimeNoteId } from './runtime.js';
+import { generateIdWithLabel, nowISO } from './ids.js';
+import { mutateState } from './state.js';
+export function materializeFederationSignal(signal, cwd) {
+    const origin = `remote:${signal.from.project_name}:${signal.from.agent_name}`;
+    if (signal.type === 'candidate') {
+        const parsed = CandidateSchema.safeParse(signal.payload);
+        if (!parsed.success)
+            return false;
+        const { id, short_label } = generateCandidateIdWithLabel(cwd);
+        saveCandidate({
+            ...parsed.data,
+            id,
+            short_label,
+            created_at: nowISO(),
+            source: undefined, // remote signal — treated as 'human' (legacy default)
+            star_count: 0,
+            starred_by: [],
+            usage_count: 0,
+            usage_events: [],
+            status: 'pending',
+        }, cwd);
+        return true;
+    }
+    if (signal.type === 'handoff') {
+        const parsed = HandoffSchema.safeParse(signal.payload);
+        if (!parsed.success)
+            return false;
+        const { id, short_label } = generateIdWithLabel('open_handoffs', cwd);
+        mutateState((state) => {
+            state.open_handoffs.push({
+                ...parsed.data,
+                id,
+                short_label,
+                created_at: nowISO(),
+                tags: [...(parsed.data.tags ?? []), origin],
+            });
+        }, cwd);
+        return true;
+    }
+    if (signal.type === 'runtime_note') {
+        const parsed = RuntimeNoteSchema.safeParse(signal.payload);
+        if (!parsed.success)
+            return false;
+        saveRuntimeNote({
+            ...parsed.data,
+            id: generateRuntimeNoteId(),
+            created_at: nowISO(),
+            tags: [...(parsed.data.tags ?? []), origin],
+        }, cwd);
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=federation-materialize.js.map

package/dist/core/instruction-templates.js

@@ -236,6 +236,8 @@ function renderSessionProtocol() {
         '- Drive a turn in a loop already assigned to you → `bclaw_loop(intent=turn|complete_turn|advance|close)`',
         '',
         'Do NOT call `bclaw_loop(intent=open)` directly — it creates a loop structure without dispatch, so the reviewer/participant never gets the work. Use the goal entries above.',
+        '',
+        '_How to verify a dispatch actually worked:_ `execution_status="delivered_and_started"` only means the brief-ack sentinel was touched — it does NOT mean the worker is doing useful work. Always (1) `bclaw_find(entity="agent_run", filter={assignment_id})` to read the spawn record; (2) check OS pid liveness yourself (`Get-Process -Id <pid>` on Windows, `kill -0 <pid>` on POSIX); (3) if the worker is silent, read its captured streams at `.brainclaw/coordination/runtime/log/<assignment_id>.{stdout,stderr}.log`. Full FSM tables + diagnostic decision tree in `docs/concepts/dispatch-lifecycle.md`.',
     ].join('\n');
 }
 function renderUserWorkflow() {