brainclaw 1.5.5 → 1.6.0

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() {

package/dist/core/loops/bootstrap-acquire.js

@@ -0,0 +1,195 @@
+/**
+ * pln#518 step 1 — bootstrap-loop singleton acquire path.
+ *
+ * Extracts the find-existing + coordination-lock + openLoop sequence from the
+ * bclaw_coordinate ideate handler so that both the CLI (`brainclaw
+ * bootstrap-loop`) and the MCP facade share the same code path. Previously
+ * the CLI used a bare `listLoops` scan without acquiring any lock, allowing
+ * two concurrent CLI invocations to both pass the scan and call `openLoop`
+ * directly — bypassing the singleton acquire and producing duplicate loops.
+ *
+ * Algorithm (lock is opportunistic, not blocking):
+ *   1. Find an existing bootstrap loop in {open, paused} → join it.
+ *   2. Atomically acquire the coordination-lock claim. If another caller won,
+ *      re-find once; join if now visible, else throw
+ *      `BootstrapCoordinationInProgressError`.
+ *   3. Call `openLoop`, release the lock (success or fail).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { acquireClaimScope, listClaims, releaseClaim } from '../claims.js';
+import { BOOTSTRAP_PRESET } from './presets/bootstrap.js';
+import { listLoops, openLoop } from './store.js';
+export class BootstrapCoordinationInProgressError extends Error {
+    blockingClaimId;
+    constructor(blockingClaimId) {
+        super(`another coordinator is currently opening a bootstrap loop (claim ${blockingClaimId}); retry shortly.`);
+        this.name = 'BootstrapCoordinationInProgressError';
+        this.blockingClaimId = blockingClaimId;
+    }
+}
+// ---- internal helpers -------------------------------------------------------
+/**
+ * Resolve symlinks + relative segments and normalize casing on
+ * case-insensitive filesystems (Windows) so that two callers
+ * reaching the same directory via different path representations
+ * always produce the same lock scope key.
+ */
+export function normalizeLockKey(cwd) {
+    let normalized;
+    try {
+        normalized = fs.realpathSync(cwd);
+    }
+    catch {
+        // Path may not exist (yet) — fall back to path.resolve which still
+        // strips relative segments + normalizes separators.
+        normalized = path.resolve(cwd);
+    }
+    // Windows: case-insensitive filesystem, normalize to lower case.
+    if (process.platform === 'win32') {
+        normalized = normalized.toLowerCase();
+    }
+    return normalized;
+}
+/** Returns the first active/paused bootstrap loop, or undefined. */
+export function findExistingBootstrapLoop(cwd) {
+    const all = listLoops({ kind: 'ideation' }, cwd);
+    return all.find((l) => l.protocol?.preset === 'bootstrap' && (l.status === 'open' || l.status === 'paused'));
+}
+/**
+ * pln#518 step 4 — orphan-lock TTL sweep.
+ *
+ * A process crash between `saveClaim(lock)` and the release branches in
+ * `acquireBootstrapLoop` leaves the opportunistic coordination lock active
+ * forever. Subsequent bootstrap callers would surface
+ * `BootstrapCoordinationInProgressError` to the operator until manual
+ * cleanup. This sweep releases any active lock that:
+ *   - matches the bootstrap-coordination-lock scope key for `cwd`, AND
+ *   - is older than `ttlMs` (default 5 minutes), AND
+ *   - has NO backing bootstrap loop materialized (releasing while a loop
+ *     IS being opened would mask a real-time race; we only sweep true
+ *     orphans).
+ *
+ * Best-effort: never throws. Returns the count of locks released so callers
+ * can surface the action in warnings if useful.
+ */
+const DEFAULT_LOCK_TTL_MS = 5 * 60 * 1000; // 5 minutes
+export function sweepOrphanBootstrapLocks(cwd, opts = {}) {
+    const ttlMs = opts.ttlMs ?? DEFAULT_LOCK_TTL_MS;
+    const now = opts.now ?? new Date();
+    const lockScope = `bootstrap-coordination-lock:${normalizeLockKey(cwd ?? process.cwd())}`;
+    // If a backing loop already exists, do NOT sweep — a concurrent acquire
+    // might be mid-flight and the lock is legitimate. The findExisting check
+    // in acquireBootstrapLoop will catch the loop before we even reach the
+    // lock check, so sweeping here would only catch stuck-mid-open cases.
+    const backingLoop = findExistingBootstrapLoop(cwd);
+    if (backingLoop)
+        return { released: 0 };
+    let released = 0;
+    try {
+        const claims = listClaims(cwd);
+        for (const claim of claims) {
+            if (claim.status !== 'active' || claim.scope !== lockScope)
+                continue;
+            const createdAt = new Date(claim.created_at).getTime();
+            if (Number.isNaN(createdAt))
+                continue;
+            const ageMs = now.getTime() - createdAt;
+            if (ageMs <= ttlMs)
+                continue;
+            try {
+                releaseClaim(claim.id, cwd);
+                released += 1;
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    catch {
+        /* best-effort: never throw on sweep failure */
+    }
+    return { released };
+}
+// ---- main export ------------------------------------------------------------
+/**
+ * Singleton acquire path for the bootstrap loop.
+ *
+ * Callers must NOT call `openLoop` themselves for bootstrap — this function
+ * is the sole entry point. Both the CLI and the MCP bclaw_coordinate ideate
+ * handler delegate here.
+ *
+ * Throws `BootstrapCoordinationInProgressError` when a coordination lock is
+ * held by a concurrent caller and no loop has materialised yet; callers
+ * should surface this to the operator with a "retry shortly" message.
+ *
+ * All other errors (e.g. from `openLoop`) propagate as-is.
+ */
+export function acquireBootstrapLoop(opts, cwd) {
+    const warnings = [];
+    // Step 1 — find an already-open loop.
+    const existing = findExistingBootstrapLoop(cwd);
+    if (existing) {
+        warnings.push(`bootstrap loop already open on this project (${existing.id}, phase=${existing.current_phase}, status=${existing.status}); joined existing instead of opening a duplicate.`);
+        return { action: 'joined', loop: existing, warnings };
+    }
+    // Step 1b — sweep any stale orphan coordination locks before the acquire
+    // (pln#518 step 4). Without this, a crash between saveClaim(lock) and the
+    // release branches would block all future bootstrap callers indefinitely.
+    const sweep = sweepOrphanBootstrapLocks(cwd);
+    if (sweep.released > 0) {
+        warnings.push(`released ${sweep.released} orphan bootstrap coordination lock(s) older than the TTL with no backing loop.`);
+    }
+    // Step 2 — atomically acquire the coordination-lock claim with a
+    // normalized scope key (pln#518 step 2 — symlinks / Windows casing
+    // / relative-segment representations all map to the same key).
+    const lockScope = `bootstrap-coordination-lock:${normalizeLockKey(cwd ?? process.cwd())}`;
+    const acquireResult = acquireClaimScope({
+        scope: lockScope,
+        agent: opts.actor,
+        agent_id: opts.agent_id,
+        description: `bootstrap coordination lock (open by ${opts.actor})`,
+        user: process.env.USER || process.env.USERNAME || undefined,
+        session_id: opts.session_id,
+        model: opts.model,
+    }, cwd);
+    if (!acquireResult.acquired) {
+        // Lost race — re-check once: the holder may have just finished opening the loop.
+        const reFound = findExistingBootstrapLoop(cwd);
+        if (reFound) {
+            warnings.push(`bootstrap loop opened by a parallel coordinator (${reFound.id}); joined existing.`);
+            return { action: 'joined', loop: reFound, warnings };
+        }
+        throw new BootstrapCoordinationInProgressError(acquireResult.conflicting_claim.id);
+    }
+    // Step 3 — open the loop, release the lock.
+    const lockClaimId = acquireResult.claim.id;
+    try {
+        const loop = openLoop({
+            kind: 'ideation',
+            title: opts.title ?? 'Bootstrap PROJECT.md',
+            goal: opts.goal,
+            created_by: opts.created_by ?? opts.agent_id ?? opts.actor,
+            slots: [
+                {
+                    role: 'champion',
+                    agent: opts.actor,
+                    ...(opts.agent_id ? { agent_id: opts.agent_id } : {}),
+                },
+            ],
+            phases: BOOTSTRAP_PRESET.phases,
+            stop_condition: BOOTSTRAP_PRESET.stop_condition,
+            protocol: BOOTSTRAP_PRESET.protocol,
+        }, cwd);
+        return { action: 'opened', loop, warnings };
+    }
+    finally {
+        try {
+            releaseClaim(lockClaimId, cwd);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+//# sourceMappingURL=bootstrap-acquire.js.map

package/dist/core/loops/facade-schema.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { LOOP_KINDS, LOOP_STATUSES, LoopLinksSchema, LoopPhaseSchema, LoopRefSchema, LoopSlotSchema, REVIEW_MODES, StopConditionSchema, } from './types.js';
+import { LOOP_KINDS, LOOP_STATUSES, LoopLinksSchema, LoopPhaseSchema, LoopRefSchema, LoopSlotSchema, ON_TIMEOUT_POLICIES, OperatorQuestionOptionSchema, PAUSE_SCOPES, RESOLVED_VIA, REVIEW_MODES, StopConditionSchema, } from './types.js';
 /**
  * `bclaw_loop(intent)` request schemas — one per intent, unioned into a
  * discriminated schema. Mirrors the BclawLoopInput type from the v8 RFC.
@@ -7,6 +7,7 @@ import { LOOP_KINDS, LOOP_STATUSES, LoopLinksSchema, LoopPhaseSchema, LoopRefSch
 const CallerEnvelopeFields = {
     agent: z.string().optional(),
     agentId: z.string().optional(),
+    project: z.string().optional(),
     client_request_id: z.string().min(1).optional(),
 };
 /**
@@ -73,6 +74,8 @@ export const BclawLoopCompleteTurnSchema = z.object({
         type: z.string().min(1),
         body: z.string().optional(),
         ref: LoopRefSchema.optional(),
+        /** pln#492 synthesis audit trail. Required when type === 'plan_draft'. */
+        addresses_critique: z.array(z.string().min(1)).optional(),
     })
         .optional(),
     expected_version: z.number().int().nonnegative().optional(),
@@ -96,6 +99,8 @@ export const BclawLoopAddArtifactSchema = z.object({
         body: z.string().optional(),
         produced_by: z.string().optional(),
         ref: LoopRefSchema.optional(),
+        /** pln#492 synthesis audit trail. Required when type === 'plan_draft'. */
+        addresses_critique: z.array(z.string().min(1)).optional(),
     }),
     expected_version: z.number().int().nonnegative().optional(),
     ...CallerEnvelopeFields,
@@ -121,6 +126,64 @@ export const BclawLoopCloseSchema = z.object({
     expected_version: z.number().int().nonnegative().optional(),
     ...CallerEnvelopeFields,
 });
+/**
+ * pln#508 step 2 — `bclaw_loop(intent='request_input')`.
+ *
+ * A slot pauses on an operator question. The handler generates a fresh
+ * `question_id`, JSON-encodes the OperatorQuestionBody, attaches it as an
+ * `operator_question` artifact, appends the id to `LoopThread.open_questions`,
+ * and transitions either the slot (`pause_scope='slot'` → status=waiting_input)
+ * or the whole loop (`pause_scope='loop'` → status=paused, pause_reason='awaiting_operator').
+ *
+ * Refused when the loop is not in status='open' (no compounding pauses) and
+ * when `loop.protocol.max_operator_questions` is already reached (anti
+ * autonomy-gap cap, e.g. the bootstrap preset sets max=3).
+ */
+export const BclawLoopRequestInputSchema = z.object({
+    intent: z.literal('request_input'),
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    slot_id: z.string().min(1),
+    phase: z.string().min(1),
+    question_text: z.string().min(1).max(500),
+    evidence: z.array(z.string().min(1)).min(1),
+    suggested_default: z.string().optional(),
+    options: z.array(OperatorQuestionOptionSchema).min(2).max(4).optional(),
+    pause_scope: z.enum(PAUSE_SCOPES),
+    on_timeout: z.enum(ON_TIMEOUT_POLICIES),
+    timeout_at: z.string().datetime().optional(),
+    expected_version: z.number().int().nonnegative().optional(),
+    ...CallerEnvelopeFields,
+});
+/**
+ * pln#508 step 2 — `bclaw_loop(intent='provide_input')`.
+ *
+ * Resolves an open operator_question. Idempotency: if `replies_to` is no
+ * longer in `loop.open_questions` but an existing operator_answer artifact
+ * references it, the existing answer is returned (no new artifact created).
+ * Unknown `replies_to` → `unknown_question` error.
+ *
+ * Resume logic:
+ * - If the source question had `pause_scope='slot'`, the asking slot
+ *   (`by_slot_id`) transitions from `waiting_input` back to `working`.
+ * - If `pause_scope='loop'` AND `open_questions` becomes empty AND the
+ *   loop is paused on `awaiting_operator`, the loop resumes to status='open'.
+ */
+export const BclawLoopProvideInputSchema = z.object({
+    intent: z.literal('provide_input'),
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    replies_to: z.string().regex(/^qst_[0-9a-z]+$/),
+    resolved_via: z.enum(RESOLVED_VIA),
+    answer_text: z.string().optional(),
+    chosen_option_id: z.string().optional(),
+    /**
+     * Defaults to 'operator'. The timeout machinery (pln#508 step 3) calls
+     * the underlying verb with `by='system'` to create synthetic answers,
+     * but external callers should leave this absent.
+     */
+    by: z.enum(['operator', 'system']).optional(),
+    expected_version: z.number().int().nonnegative().optional(),
+    ...CallerEnvelopeFields,
+});
 export const BclawLoopRequestSchema = z.discriminatedUnion('intent', [
     BclawLoopOpenSchema,
     BclawLoopGetSchema,
@@ -132,6 +195,8 @@ export const BclawLoopRequestSchema = z.discriminatedUnion('intent', [
     BclawLoopPauseSchema,
     BclawLoopResumeSchema,
     BclawLoopCloseSchema,
+    BclawLoopRequestInputSchema,
+    BclawLoopProvideInputSchema,
 ]);
 export const BCLAW_LOOP_INTENTS = [
     'open',
@@ -144,5 +209,7 @@ export const BCLAW_LOOP_INTENTS = [
     'pause',
     'resume',
     'close',
+    'request_input',
+    'provide_input',
 ];
 //# sourceMappingURL=facade-schema.js.map

package/dist/core/loops/hooks/bootstrap-write.js

@@ -0,0 +1,144 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryDir, writeFileAtomic } from '../../io.js';
+import { nowISO } from '../../ids.js';
+import { LoopArtifactSchema, RefBasedArtifactBodySchema, } from '../types.js';
+/**
+ * Directory where ref-based artifact payloads for a given loop live on disk.
+ * No central helper exists yet, so this is the canonical place to compute it.
+ * Layout mirrors the thread/event storage convention in store.ts:
+ *
+ *   <memoryDir>/loops/threads/<loop_id>/artifacts/<ref>
+ */
+function loopArtifactsDir(loopId, cwd) {
+    return path.join(memoryDir(cwd ?? process.cwd()), 'loops', 'threads', loopId, 'artifacts');
+}
+/**
+ * Returns the most recently produced `project_md_final` artifact on the loop,
+ * or `undefined` if none has been added yet. Artifacts on `loop.artifacts` are
+ * appended in production order, so the last match is "latest".
+ */
+function findLatestFinal(loop) {
+    for (let i = loop.artifacts.length - 1; i >= 0; i--) {
+        const a = loop.artifacts[i];
+        if (a.type === 'project_md_final')
+            return a;
+    }
+    return undefined;
+}
+/**
+ * Parse the ref-based body off a known-typed loop artifact. The
+ * LoopArtifactSchema validator already enforces the JSON shape, so any failure
+ * here points at a corrupt thread file rather than schema drift.
+ */
+function parseRefBody(artifact) {
+    if (!artifact.body) {
+        throw new Error(`writeProjectMdSafe: artifact ${artifact.artifact_id} (type=${artifact.type}) has no body — expected ref-based payload`);
+    }
+    return RefBasedArtifactBodySchema.parse(JSON.parse(artifact.body));
+}
+/**
+ * Hand-rolled unified-diff renderer.
+ *
+ * Phase 0 spec §file_overwrite_approval explicitly accepts a coarse diff for
+ * v1 — the operator reads it; nothing automated patches with it. So we render
+ * every old line as `-` and every new line as `+` under a single `@@` hunk
+ * header. Output is stable and deterministic.
+ */
+function generateUnifiedDiff(oldContent, newContent, oldLabel, newLabel) {
+    const oldLines = oldContent.length === 0 ? [] : oldContent.split(/\r?\n/);
+    const newLines = newContent.length === 0 ? [] : newContent.split(/\r?\n/);
+    const oldCount = oldLines.length;
+    const newCount = newLines.length;
+    const oldStart = oldCount === 0 ? 0 : 1;
+    const newStart = newCount === 0 ? 0 : 1;
+    const lines = [];
+    lines.push(`--- ${oldLabel}`);
+    lines.push(`+++ ${newLabel}`);
+    lines.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
+    for (const l of oldLines)
+        lines.push(`-${l}`);
+    for (const l of newLines)
+        lines.push(`+${l}`);
+    return lines.join('\n');
+}
+function sha256Hex(content) {
+    return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/**
+ * pln#512 step 1 — IMPL.
+ *
+ * @see WriteProjectMdResult
+ * @see WriteProjectMdOptions
+ */
+export function writeProjectMdSafe(loop, cwd, opts) {
+    const resolvedCwd = cwd ?? process.cwd();
+    const target_path = path.join(resolvedCwd, 'PROJECT.md');
+    const finalArtifact = findLatestFinal(loop);
+    if (!finalArtifact) {
+        return {
+            needs_approval: false,
+            target_path,
+            written: false,
+            reason: 'no_final_artifact',
+        };
+    }
+    const body = parseRefBody(finalArtifact);
+    const sourcePath = path.join(loopArtifactsDir(loop.id, resolvedCwd), body.ref);
+    const sourceContent = fs.readFileSync(sourcePath, 'utf8');
+    const exists = fs.existsSync(target_path);
+    const isEmpty = exists && fs.statSync(target_path).size === 0;
+    if (!exists || isEmpty) {
+        writeFileAtomic(target_path, sourceContent);
+        return {
+            needs_approval: false,
+            target_path,
+            written: true,
+            reason: exists ? 'empty' : 'absent',
+        };
+    }
+    // pln#512 step 2 — approval short-circuit. When the operator has already
+    // signed off on the overwrite (via a resolved file_overwrite_approval
+    // question), the caller passes opts.approved=true and we write atomically
+    // without re-generating a diff artifact. Mirrors the absent/empty branch
+    // semantics so callers see a unified shape.
+    if (opts?.approved === true) {
+        writeFileAtomic(target_path, sourceContent);
+        return {
+            needs_approval: false,
+            target_path,
+            written: true,
+            reason: 'present_non_empty',
+        };
+    }
+    // Present + non-empty → build a file_diff artifact for operator approval.
+    // We do NOT touch the loop thread or the target file; the caller (step 2)
+    // splices the artifact onto the thread under request_input.
+    const existingContent = fs.readFileSync(target_path, 'utf8');
+    const diff = generateUnifiedDiff(existingContent, sourceContent, 'PROJECT.md', 'PROJECT.md (proposed)');
+    const artifactId = `art_${crypto.randomBytes(6).toString('hex')}`;
+    const patchRef = `${artifactId}.patch`;
+    const patchPath = path.join(loopArtifactsDir(loop.id, resolvedCwd), patchRef);
+    fs.mkdirSync(path.dirname(patchPath), { recursive: true });
+    writeFileAtomic(patchPath, diff);
+    const refBody = {
+        ref: patchRef,
+        byte_count: Buffer.byteLength(diff, 'utf8'),
+        sha256: sha256Hex(diff),
+    };
+    const diff_artifact = LoopArtifactSchema.parse({
+        artifact_id: artifactId,
+        phase: finalArtifact.phase,
+        type: 'file_diff',
+        body: JSON.stringify(refBody),
+        produced_at: nowISO(),
+    });
+    return {
+        needs_approval: true,
+        target_path,
+        diff_artifact,
+        reason: 'present_non_empty',
+    };
+}
+//# sourceMappingURL=bootstrap-write.js.map