brainclaw 1.5.4 → 1.6.0

package/dist/commands/questions.js

@@ -0,0 +1,180 @@
+import { memoryExists } from '../core/io.js';
+import { listLoops, listLoopEvents } from '../core/loops/index.js';
+import { resolveCurrentAgentName } from '../core/agent-registry.js';
+function parseQuestionBody(artifact) {
+    if (artifact.type !== 'operator_question' || !artifact.body)
+        return undefined;
+    try {
+        return JSON.parse(artifact.body);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseAnswerBody(artifact) {
+    if (artifact.type !== 'operator_answer' || !artifact.body)
+        return undefined;
+    try {
+        return JSON.parse(artifact.body);
+    }
+    catch {
+        return undefined;
+    }
+}
+function relativeAge(seconds) {
+    if (seconds < 60)
+        return `${Math.max(0, Math.floor(seconds))}s ago`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m ago`;
+    if (seconds < 86400)
+        return `${Math.floor(seconds / 3600)}h ago`;
+    return `${Math.floor(seconds / 86400)}d ago`;
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max - 1)}…`;
+}
+function findAnswerFor(loop, questionId) {
+    for (const artifact of loop.artifacts) {
+        const body = parseAnswerBody(artifact);
+        if (body && body.replies_to === questionId) {
+            return { artifact, body };
+        }
+    }
+    return undefined;
+}
+function loopWasTimedOut(loop, questionId, cwd) {
+    if (loop.status === 'cancelled') {
+        // Check events for pause_timeout that targeted this question with cancel_loop
+        try {
+            const events = listLoopEvents(loop.id, cwd);
+            for (const ev of events) {
+                if (ev.kind === 'pause_timeout' && ev.question_id === questionId && ev.action_taken === 'cancel_loop') {
+                    return true;
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return false;
+}
+function determineStatus(loop, questionBody, cwd) {
+    if (loop.open_questions.includes(questionBody.question_id)) {
+        return { status: 'awaiting' };
+    }
+    const answer = findAnswerFor(loop, questionBody.question_id);
+    if (answer) {
+        const isTimedOut = answer.body.by === 'system' || answer.body.resolved_via === 'timeout_default';
+        const answerInfo = {
+            resolved_via: answer.body.resolved_via,
+            answer_text: answer.body.answer_text,
+            chosen_option_id: answer.body.chosen_option_id,
+            by: answer.body.by,
+            synthetic: answer.body.synthetic === true,
+            produced_at: answer.artifact.produced_at,
+        };
+        return { status: isTimedOut ? 'timed_out' : 'answered', answer: answerInfo };
+    }
+    if (loopWasTimedOut(loop, questionBody.question_id, cwd)) {
+        return { status: 'timed_out' };
+    }
+    // No answer artifact and not in open_questions — treat as answered for safety.
+    return { status: 'answered' };
+}
+function collectQuestions(loops, cwd, now) {
+    const rows = [];
+    for (const loop of loops) {
+        for (const artifact of loop.artifacts) {
+            const body = parseQuestionBody(artifact);
+            if (!body)
+                continue;
+            const { status, answer } = determineStatus(loop, body, cwd);
+            const producedAtMs = Date.parse(artifact.produced_at);
+            const ageSeconds = Number.isFinite(producedAtMs)
+                ? Math.max(0, (now - producedAtMs) / 1000)
+                : 0;
+            rows.push({
+                question_id: body.question_id,
+                loop_id: loop.id,
+                loop_title: loop.title,
+                phase: artifact.phase,
+                status,
+                question_text: body.question_text,
+                evidence: body.evidence,
+                suggested_default: body.suggested_default,
+                options: body.options,
+                pause_scope: body.pause_scope,
+                on_timeout: body.on_timeout,
+                timeout_at: body.timeout_at,
+                produced_at: artifact.produced_at,
+                age_seconds: ageSeconds,
+                answer,
+            });
+        }
+    }
+    return rows;
+}
+function formatTable(rows) {
+    if (rows.length === 0)
+        return 'No questions match the current filters.';
+    const header = ['QUESTION_ID', 'LOOP_ID', 'STATUS', 'QUESTION', 'AGE'];
+    const data = rows.map((r) => [
+        r.question_id,
+        r.loop_id,
+        r.status,
+        truncate(r.question_text, 50),
+        relativeAge(r.age_seconds),
+    ]);
+    const widths = header.map((h, i) => Math.max(h.length, ...data.map((row) => row[i].length)));
+    const pad = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join('  ').trimEnd();
+    const lines = [pad(header), pad(widths.map((w) => '-'.repeat(w)))];
+    for (const row of data)
+        lines.push(pad(row));
+    return lines.join('\n');
+}
+/**
+ * `brainclaw questions` — list operator_question artifacts across loops in
+ * the current project. Filters by --loop, --status, --mine; emits a human
+ * table or --json.
+ *
+ * v1 caveat: question targeting (which agent should answer) isn't tracked
+ * on the artifact body yet. The --mine filter therefore returns ALL awaiting
+ * questions for human callers; agent callers see none (since no question is
+ * provably theirs). Documented in the brief.
+ */
+export function runQuestionsCommand(options = {}, cwd) {
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const status = options.status ?? 'awaiting';
+    const allLoops = listLoops({}, cwd);
+    const loops = options.loop
+        ? allLoops.filter((l) => l.id === options.loop)
+        : allLoops;
+    const now = Date.now();
+    let rows = collectQuestions(loops, cwd, now);
+    rows = rows.filter((r) => r.status === status);
+    if (options.mine) {
+        const caller = resolveCurrentAgentName(cwd);
+        const isHuman = !/^(claude|codex|copilot|gemini|opencode|cline|continue|antigravity|sonnet|opus|haiku)/i.test(caller);
+        if (!isHuman) {
+            // Agent callers can't prove ownership of any question — return empty
+            // until question targeting is tracked (v1 heuristic).
+            rows = [];
+        }
+        // For humans, --mine is a no-op in v1 because question targeting isn't tracked.
+    }
+    rows.sort((a, b) => b.produced_at.localeCompare(a.produced_at));
+    const result = { questions: rows };
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    console.log(formatTable(rows));
+    return result;
+}
+//# sourceMappingURL=questions.js.map

package/dist/commands/reply.js

@@ -0,0 +1,190 @@
+import { memoryExists } from '../core/io.js';
+import { computeNextExpected, listLoops, provideInput } from '../core/loops/index.js';
+import { resolveCurrentAgentName } from '../core/agent-registry.js';
+// NextExpectedHint imported from `../core/loops/index.js` — single
+// source of truth shared with the MCP facade (hoisted per can_e57c7782).
+function fail(message, exitCode, opts) {
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    }
+    else {
+        console.error(`Error: ${message}`);
+    }
+    process.exit(exitCode);
+}
+function parseQuestionBody(artifact) {
+    if (artifact.type !== 'operator_question' || !artifact.body)
+        return undefined;
+    try {
+        return JSON.parse(artifact.body);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseAnswerBody(artifact) {
+    if (artifact.type !== 'operator_answer' || !artifact.body)
+        return undefined;
+    try {
+        return JSON.parse(artifact.body);
+    }
+    catch {
+        return undefined;
+    }
+}
+function findLoopForQuestion(loops, questionId) {
+    for (const loop of loops) {
+        for (const artifact of loop.artifacts) {
+            const body = parseQuestionBody(artifact);
+            if (body && body.question_id === questionId) {
+                const isOpen = loop.open_questions.includes(questionId);
+                let existingAnswer;
+                if (!isOpen) {
+                    for (const a of loop.artifacts) {
+                        const ab = parseAnswerBody(a);
+                        if (ab && ab.replies_to === questionId) {
+                            existingAnswer = ab;
+                            break;
+                        }
+                    }
+                }
+                return { loop, question: body, isOpen, existingAnswer };
+            }
+        }
+    }
+    return undefined;
+}
+function formatNextExpected(hint) {
+    if (!hint)
+        return '  (loop has no further expected action)';
+    const bits = [`  next: ${hint.action} (${hint.intent})`];
+    if (hint.phase)
+        bits.push(`  phase: ${hint.phase}`);
+    if (hint.slot_id)
+        bits.push(`  slot: ${hint.slot_id}${hint.role ? ` [${hint.role}]` : ''}`);
+    if (hint.from_phase && hint.to_phase)
+        bits.push(`  ${hint.from_phase} → ${hint.to_phase}`);
+    if (hint.blocking_on.length)
+        bits.push(`  blocking_on: ${hint.blocking_on.join(', ')}`);
+    if (hint.reason)
+        bits.push(`  reason: ${hint.reason}`);
+    return bits.join('\n');
+}
+/**
+ * `brainclaw reply <qst_id>` — wraps the provideInput verb. Locates the loop
+ * containing the question, validates the requested resolution against the
+ * question's options/suggested_default, and prints the resulting next_expected
+ * hint on success.
+ *
+ * Exit codes:
+ *   0 — success.
+ *   1 — validation error (unknown qst, already resolved, mutually-exclusive
+ *       flags, missing flags, invalid option id, --skip without default).
+ *   2 — verb threw a domain error (e.g. terminal loop status).
+ */
+export function runReplyCommand(questionId, options = {}, cwd) {
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    // Validate mutually-exclusive resolution flags.
+    const modes = [];
+    if (options.answer !== undefined)
+        modes.push('answer');
+    if (options.choose !== undefined)
+        modes.push('choose');
+    if (options.skip)
+        modes.push('skip');
+    if (modes.length === 0) {
+        fail('reply requires exactly one of --answer <text>, --choose <option_id>, or --skip', 1, options);
+    }
+    if (modes.length > 1) {
+        fail(`--answer, --choose, and --skip are mutually exclusive (got: ${modes.join(', ')})`, 1, options);
+    }
+    const mode = modes[0];
+    // Validate qst id format up-front so we can give a nicer error than
+    // "unknown question" for typos like `brainclaw reply foo`.
+    if (!/^qst_[0-9a-z]+$/.test(questionId)) {
+        fail(`invalid question_id "${questionId}" — expected format qst_<hex>`, 1, options);
+    }
+    const loops = listLoops({}, cwd);
+    const located = findLoopForQuestion(loops, questionId);
+    if (!located) {
+        fail(`question not found: ${questionId} (run \`brainclaw questions\` to list pending questions)`, 1, options);
+    }
+    const { loop, question, isOpen, existingAnswer } = located;
+    if (!isOpen) {
+        if (mode === 'answer' || mode === 'choose') {
+            const detail = existingAnswer
+                ? ` (resolved via ${existingAnswer.resolved_via}${existingAnswer.by === 'system' ? ', synthetic' : ''})`
+                : '';
+            fail(`question already resolved: ${questionId}${detail}`, 1, options);
+        }
+        // --skip on an already-resolved question is treated as idempotent replay:
+        // provideInput's idempotent path returns the existing answer artifact.
+    }
+    if (mode === 'choose') {
+        const optionId = options.choose;
+        const opts = question.options ?? [];
+        const found = opts.find((o) => o.id === optionId);
+        if (!found) {
+            const known = opts.map((o) => o.id).join(', ') || '<none>';
+            fail(`--choose ${optionId}: question ${questionId} has no such option (known: ${known})`, 1, options);
+        }
+    }
+    // pln#512 phase 3 codex review fix #2: when the source question carries
+    // structured options, `--answer` cannot resolve it correctly. The verb
+    // post-hooks (e.g. file_overwrite_approval) branch on chosen_option_id,
+    // so a free-text answer of "approve" creates an answer artifact whose
+    // chosen_option_id is empty — the hook treats that as REJECT. Refuse the
+    // mode mismatch up front and point the operator at --choose.
+    if (mode === 'answer' && question.options && question.options.length > 0) {
+        const opts = question.options;
+        const known = opts.map((o) => o.id).join(', ');
+        const text = (options.answer ?? '').trim();
+        const matchedOption = opts.find((o) => o.id === text);
+        const hint = matchedOption
+            ? ` — to pick this option, use \`--choose ${matchedOption.id}\``
+            : ` — pick one with \`--choose <id>\` (known: ${known})`;
+        fail(`question ${questionId} has structured options; --answer is not accepted${hint}`, 1, options);
+    }
+    if (mode === 'skip' && question.suggested_default === undefined) {
+        fail(`--skip on ${questionId}: source question has no suggested_default to materialize`, 1, options);
+    }
+    const actor = resolveCurrentAgentName(cwd);
+    const resolvedVia = mode === 'answer' ? 'answer' : mode === 'choose' ? 'choose' : 'skip';
+    let result;
+    try {
+        result = provideInput({
+            loop_id: loop.id,
+            replies_to: questionId,
+            resolved_via: resolvedVia,
+            answer_text: mode === 'answer' ? options.answer : undefined,
+            chosen_option_id: mode === 'choose' ? options.choose : undefined,
+            actor,
+        }, cwd);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        fail(`provide_input verb rejected the call: ${message}`, 2, options);
+    }
+    const hint = computeNextExpected(result.thread);
+    const out = {
+        ok: true,
+        loop_id: loop.id,
+        question_id: questionId,
+        resolved_via: resolvedVia,
+        artifact_id: result.artifact_id,
+        next_expected: hint,
+        duplicate: result.duplicate || undefined,
+    };
+    if (options.json) {
+        console.log(JSON.stringify(out, null, 2));
+        return out;
+    }
+    const prefix = result.duplicate ? '↺ Replay-acked' : '✔ Answered';
+    console.log(`${prefix} ${questionId} via ${resolvedVia} on loop ${loop.id}`);
+    console.log(formatNextExpected(hint));
+    return out;
+}
+//# sourceMappingURL=reply.js.map

package/dist/commands/session-end.js

@@ -9,6 +9,7 @@ import { loadState, persistState } from '../core/state.js';
 import { listArchivedCandidates, listCandidates } from '../core/candidates.js';
 import { createFederationMessage } from '../core/federation-message.js';
 import { pushSignal } from '../core/federation-transport.js';
+import { pushSignalToCloud, isCloudSyncEnabled } from '../core/federation-cloud.js';
 import { loadConfig } from '../core/config.js';
 import { resolveCrossProjectLinks } from '../core/cross-project.js';
 import { createCandidateFromInput } from './reflect.js';
@@ -25,9 +26,9 @@ export const REFLECTION_QUESTIONS = [
     'What should have been done differently (design, process, or approach)?',
     'What should brainclaw itself improve based on this session?',
 ];
-export function runSessionEnd(options = {}) {
+export async function runSessionEnd(options = {}) {
     try {
-        const result = endSession(options);
+        const result = await endSession(options);
         if (options.json) {
             console.log(JSON.stringify(result, null, 2));
             return;
@@ -97,7 +98,7 @@ export function runSessionEnd(options = {}) {
         process.exit(1);
     }
 }
-export function endSession(options = {}) {
+export async function endSession(options = {}) {
     if (!memoryExists(options.cwd)) {
         throw new Error('.brainclaw/ not found. Run `brainclaw init` first.');
     }
@@ -303,6 +304,24 @@ export function endSession(options = {}) {
     if (pushedSignals > 0 && !options.json) {
         console.log(`✔ Pushed ${pushedSignals} signal(s) to linked projects`);
     }
+    // Cloud federation push (Phase 1 — opt-in via cloud_sync.enabled)
+    let pushedCloudSignals = 0;
+    if (isCloudSyncEnabled(options.cwd)) {
+        try {
+            pushedCloudSignals = await pushSessionCloudSignals({
+                sessionId,
+                actor,
+                sessionNotes,
+                cwd: options.cwd,
+            });
+        }
+        catch {
+            // Non-fatal — cloud push failure should not block session end
+        }
+    }
+    if (pushedCloudSignals > 0 && !options.json) {
+        console.log(`✔ Pushed ${pushedCloudSignals} signal(s) to cloud`);
+    }
     appendAuditEntry({
         action: 'session_end',
         actor: actor.agent,
@@ -435,6 +454,89 @@ function pushSessionFederationSignals(input) {
     }
     return pushed;
 }
+/**
+ * Push session-scoped handoffs / candidates / runtime_notes to the cloud federation.
+ * Skips entities with visibility = 'machine' or 'private' — only 'shared' (default) goes out.
+ * Failures per-entity are swallowed so a single bad fetch does not abort the rest.
+ */
+async function pushSessionCloudSignals(input) {
+    const cwd = input.cwd ?? process.cwd();
+    const config = loadConfig(cwd);
+    const fromProjectName = config.project_name ?? path.basename(cwd);
+    const currentState = loadState(cwd);
+    const sessionHandoffs = currentState.open_handoffs.filter((handoff) => handoff.session_id === input.sessionId);
+    const sessionCandidates = [
+        ...listCandidates(undefined, cwd),
+        ...listArchivedCandidates('accepted', cwd),
+        ...listArchivedCandidates('rejected', cwd),
+    ].filter((candidate) => candidate.session_id === input.sessionId);
+    const sessionRuntimeNotes = input.sessionNotes.filter((note) => note.session_id === input.sessionId);
+    // Conservative cloud-push gate (review finding 2026-05-15, finalized via
+    // pln#365 finalization 2026-05-15):
+    //
+    // All four signal-bearing schemas now carry a `visibility` field:
+    //   - RuntimeNoteSchema  (schema.ts:899)  — defaults to 'shared'
+    //   - TrapSchema         (schema.ts:184)  — defaults to 'shared'
+    //   - HandoffSchema      (schema.ts:~248) — optional, no default (opt-in)
+    //   - CandidateSchema    (schema.ts:~619) — optional, no default (opt-in)
+    //
+    // Handoffs and candidates are opt-in because their text / snapshot.diff
+    // can carry per-host secrets. An agent must explicitly set
+    // `visibility: 'shared'` to push such an entity to cloud. RuntimeNotes
+    // default to shared since they're already the lightest-weight signal.
+    //
+    // The gate below is intentionally literal — `entity.visibility === 'shared'`.
+    // Undefined or absent visibility means "stay local" regardless of cloud_sync.
+    const isExplicitlyShared = (entity) => {
+        return entity.visibility === 'shared';
+    };
+    let pushed = 0;
+    const pushOne = async (entityType, entity) => {
+        const message = createFederationMessage({
+            version: 1,
+            from: {
+                project_id: input.actor.project_id ?? config.project_id,
+                project_name: fromProjectName,
+                project_path: cwd,
+                agent_name: input.actor.agent,
+                agent_id: input.actor.agent_id,
+                host_id: input.actor.host_id,
+            },
+            to: {
+                // Cloud is a broadcast bus — no specific target project at this layer.
+                project_name: 'broadcast',
+                project_path: '',
+            },
+            type: entityType,
+            payload: entity,
+            causal_parent: input.sessionId,
+        });
+        try {
+            const ok = await pushSignalToCloud(message, cwd);
+            if (ok)
+                pushed++;
+        }
+        catch {
+            // Per-entity failure should not abort the loop
+        }
+    };
+    for (const handoff of sessionHandoffs) {
+        if (!isExplicitlyShared(handoff))
+            continue;
+        await pushOne('handoff', handoff);
+    }
+    for (const candidate of sessionCandidates) {
+        if (!isExplicitlyShared(candidate))
+            continue;
+        await pushOne('candidate', candidate);
+    }
+    for (const note of sessionRuntimeNotes) {
+        if (!isExplicitlyShared(note))
+            continue;
+        await pushOne('runtime_note', note);
+    }
+    return pushed;
+}
 function resolvePublisherLink(target, publisherLinks, entityType, cwd) {
     const normalized = target.trim().toLowerCase();
     if (!normalized)

package/dist/commands/session-start.js

@@ -9,25 +9,25 @@ import { requireMinimumTrustLevel, resolveCurrentModel, resolveOrAutoRegisterAge
 import { buildContext, renderContextPromptTemplate } from '../core/context.js';
 import { writeContextMarker } from '../core/freshness.js';
 import { saveRuntimeNote, generateRuntimeNoteId } from '../core/runtime.js';
-import { nowISO, generateId, generateIdWithLabel } from '../core/ids.js';
+import { nowISO, generateId } from '../core/ids.js';
 import { appendAuditEntry } from '../core/audit.js';
 import { releaseStaleClaimsFromOtherAgents } from '../core/claims.js';
-import { SessionSnapshotSchema, CandidateSchema, HandoffSchema, RuntimeNoteSchema } from '../core/schema.js';
+import { SessionSnapshotSchema } from '../core/schema.js';
 import { auditLocalAgentWorkspaceFiles } from '../core/agent-files.js';
 import { buildAgentInventory, loadAgentInventory, saveAgentInventory, diffInventory } from '../core/agent-inventory.js';
 import { checkMemoryPressure } from '../core/gc-semantic.js';
 import { pullSignalsFromLinkedProjects, markSignalProcessed } from '../core/federation-transport.js';
-import { saveCandidate, generateCandidateIdWithLabel } from '../core/candidates.js';
-import { mutateState } from '../core/state.js';
+import { pullSignalsFromCloud, isCloudSyncEnabled } from '../core/federation-cloud.js';
+import { materializeFederationSignal } from '../core/federation-materialize.js';
 function sessionsDir(cwd) {
     return resolveEntityDir('sessions', cwd ?? process.cwd(), 'read');
 }
 function sessionSnapshotPath(sessionId, cwd) {
     return path.join(sessionsDir(cwd), `${sessionId}.json`);
 }
-export function runSessionStart(options = {}) {
+export async function runSessionStart(options = {}) {
     try {
-        const snapshot = startSession({
+        const snapshot = await startSession({
             ...options,
             maintenanceMode: options.maintenanceMode ?? 'full',
         });
@@ -96,7 +96,7 @@ export function runSessionStart(options = {}) {
         process.exit(1);
     }
 }
-export function startSession(options = {}) {
+export async function startSession(options = {}) {
     if (!memoryExists(options.cwd)) {
         throw new Error('.brainclaw/ not found. Run `brainclaw init` first.');
     }
@@ -243,60 +243,17 @@ export function startSession(options = {}) {
         }
         catch { /* non-fatal */ }
     }
-    // Materialize incoming federation signals from linked projects
+    // Materialize incoming federation signals from linked projects (Phase 0 — local)
     if (maintenanceMode === 'full') {
         try {
             const federationSignals = pullSignalsFromLinkedProjects(options.cwd);
             let materialized = 0;
             for (const signal of federationSignals) {
                 try {
-                    const origin = `remote:${signal.from.project_name}:${signal.from.agent_name}`;
-                    if (signal.type === 'candidate') {
-                        const parsed = CandidateSchema.safeParse(signal.payload);
-                        if (parsed.success) {
-                            const { id, short_label } = generateCandidateIdWithLabel(options.cwd);
-                            saveCandidate({
-                                ...parsed.data,
-                                id,
-                                short_label,
-                                created_at: nowISO(),
-                                source: undefined, // remote federation signal — treated as 'human' (legacy default)
-                                star_count: 0,
-                                starred_by: [],
-                                usage_count: 0,
-                                usage_events: [],
-                                status: 'pending',
-                            }, options.cwd);
-                        }
-                    }
-                    else if (signal.type === 'handoff') {
-                        const parsed = HandoffSchema.safeParse(signal.payload);
-                        if (parsed.success) {
-                            const { id, short_label } = generateIdWithLabel('open_handoffs', options.cwd);
-                            mutateState((state) => {
-                                state.open_handoffs.push({
-                                    ...parsed.data,
-                                    id,
-                                    short_label,
-                                    created_at: nowISO(),
-                                    tags: [...(parsed.data.tags ?? []), origin],
-                                });
-                            }, options.cwd);
-                        }
-                    }
-                    else if (signal.type === 'runtime_note') {
-                        const parsed = RuntimeNoteSchema.safeParse(signal.payload);
-                        if (parsed.success) {
-                            saveRuntimeNote({
-                                ...parsed.data,
-                                id: generateRuntimeNoteId(),
-                                created_at: nowISO(),
-                                tags: [...(parsed.data.tags ?? []), origin],
-                            }, options.cwd);
-                        }
+                    if (materializeFederationSignal(signal, options.cwd)) {
+                        materialized++;
                     }
                     markSignalProcessed(signal.from.project_path, signal.id);
-                    materialized++;
                 }
                 catch { /* skip this signal — do not block session start */ }
             }
@@ -306,6 +263,28 @@ export function startSession(options = {}) {
         }
         catch { /* Non-fatal — federation pull failure should not block session start */ }
     }
+    // Materialize incoming federation signals from cloud (Phase 1 — opt-in via cloud_sync.enabled)
+    if (maintenanceMode === 'full' && isCloudSyncEnabled(options.cwd)) {
+        try {
+            const cloudSignals = await pullSignalsFromCloud(actor.agent, { limit: 100 }, options.cwd);
+            let cloudMaterialized = 0;
+            for (const signal of cloudSignals) {
+                try {
+                    if (materializeFederationSignal(signal, options.cwd)) {
+                        cloudMaterialized++;
+                    }
+                    // No markSignalProcessed for cloud signals — cloud-side tracks delivery via the
+                    // inbox endpoint's own state (per-agent read cursor). If the cloud returns the
+                    // same signal twice, the idempotency_key field allows future dedup at materialize time.
+                }
+                catch { /* skip this signal — do not block session start */ }
+            }
+            if (cloudMaterialized > 0) {
+                console.log(`✔ Materialized ${cloudMaterialized} federation signal(s) from cloud`);
+            }
+        }
+        catch { /* Non-fatal — cloud pull failure should not block session start */ }
+    }
     return {
         ...snapshot,
         ...(agentGitHygiene.isGitRepo && (agentGitHygiene.missingGitignorePaths.length > 0 || agentGitHygiene.trackedPaths.length > 0)