brainclaw 1.5.4 → 1.6.0

package/dist/core/entity-operations.js

@@ -17,14 +17,16 @@ import { archiveCandidate, listCandidates, loadCandidate, saveCandidate, } from
 import { addCrossProjectLink, removeCrossProjectLink, resolveCrossProjectLinks, } from './cross-project.js';
 import { listClaims } from './claims.js';
 import { listActionRequired } from './actions.js';
-import { listAssignments } from './assignments.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)
@@ -309,7 +382,17 @@ export function updateEntity(name, id, patch, cwd) {
             saveRuntimeNote(patched, cwd);
             return { entity: name, id };
         }
+        case 'assignment': {
+            const assignment = loadAssignment(id, cwd);
+            if (!assignment)
+                throw new EntityNotFoundError(name, id);
+            const patched = { ...assignment, ...patch };
+            saveAssignment(patched, 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);
@@ -371,6 +454,28 @@ export function removeEntity(name, id, cwd, purge = false) {
             const removed = removeCrossProjectLink(id, cwd);
             return { entity: name, id: removed.name ?? removed.path, archived: false, purged: true };
         }
+        case 'assignment': {
+            const assignment = loadAssignment(id, cwd);
+            if (!assignment)
+                throw new EntityNotFoundError(name, id);
+            if (purge) {
+                const deleted = deleteAssignment(id, cwd);
+                if (!deleted)
+                    throw new EntityNotFoundError(name, id);
+                return { entity: name, id, archived: false, purged: true };
+            }
+            if (assignment.status === 'cancelled') {
+                return { entity: name, id, archived: true, purged: false };
+            }
+            if (ENTITY_REGISTRY.assignment.terminal.includes(assignment.status)) {
+                throw new Error(`assignment '${id}' is already terminal (${assignment.status}); use purge:true to hard-delete if needed`);
+            }
+            transitionAssignment(id, 'cancelled', {
+                actor: 'brainclaw',
+                status_reason: 'Archived via bclaw_remove',
+            }, cwd);
+            return { entity: name, id, archived: true, purged: false };
+        }
         default:
             throw new EntityOperationUnsupportedError(name, 'remove');
     }
@@ -418,6 +523,13 @@ export function transitionEntity(name, id, to, cwd, _reason) {
             }
             throw new InvalidTransitionError(name, from, to);
         }
+        case 'assignment': {
+            transitionAssignment(id, to, {
+                actor: 'brainclaw',
+                status_reason: _reason,
+            }, cwd);
+            return { entity: name, id, from, to, side_effects: sideEffects };
+        }
         default:
             throw new EntityOperationUnsupportedError(name, 'transition', `Lifecycle transitions for ${name} not yet wired.`);
     }
@@ -447,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/entity-registry.js

@@ -234,24 +234,25 @@ const assignment = {
     name: 'assignment',
     shortLabelPrefix: 'asgn',
     schema: AssignmentSchema,
-    updatable: ['brief', 'tags'],
+    updatable: ['description', 'status_reason', 'tags'],
     statusField: 'status',
     transitions: {
-        created: ['offered', 'expired'],
-        offered: ['accepted', 'expired', 'rerouted'],
-        accepted: ['started', 'failed', 'timed_out'],
-        started: ['completed', 'failed', 'blocked', 'timed_out'],
-        failed: ['retrying'],
-        timed_out: ['retrying'],
-        retrying: ['offered'],
-        blocked: ['started', 'rerouted', 'failed'],
+        created: ['offered', 'expired', 'rerouted', 'cancelled'],
+        offered: ['accepted', 'expired', 'rerouted', 'failed', 'cancelled'],
+        accepted: ['started', 'failed', 'timed_out', 'rerouted', 'cancelled'],
+        started: ['completed', 'failed', 'blocked', 'timed_out', 'rerouted', 'cancelled'],
+        failed: ['retrying', 'rerouted', 'cancelled'],
+        timed_out: ['retrying', 'rerouted', 'cancelled'],
+        retrying: ['offered', 'rerouted', 'cancelled'],
+        blocked: ['started', 'rerouted', 'failed', 'cancelled'],
     },
-    terminal: ['completed', 'expired', 'rerouted'],
+    terminal: ['completed', 'cancelled', 'expired', 'rerouted'],
     sideEffects: {
         'created->offered': ['timestamp:offered_at', 'event:assignment_offered', 'audit:assignment_offered'],
         'offered->accepted': ['timestamp:accepted_at', 'event:assignment_accepted', 'sync:agent_run'],
         'accepted->started': ['timestamp:started_at', 'event:assignment_started', 'sync:agent_run'],
         'started->completed': ['timestamp:completed_at', 'event:assignment_completed', 'sync:agent_run'],
+        'started->cancelled': ['timestamp:cancelled_at', 'event:assignment_cancelled', 'sync:agent_run'],
         'started->failed': ['timestamp:failed_at', 'event:assignment_failed', 'sync:agent_run'],
     },
 };

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,27 @@ 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.boolean().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 +87,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 +114,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() {