brainclaw 1.16.0 → 1.18.0

package/dist/core/loops/types.js

@@ -103,11 +103,28 @@ export const LoopPhaseSchema = z.object({
 export const LoopIterationSchema = z.object({
     cycle: z.array(z.string().min(1)).min(1),
     max_iterations: z.number().int().positive(),
-    exit_when: z.enum(['critic_signal', 'no_new_critique_artifacts']),
+    exit_when: z.enum(['critic_signal', 'no_new_critique_artifacts', 'command_green']),
+});
+/** pln#632 — hard ceiling + default for an engine-run verify command's wall clock. */
+export const VERIFY_TIMEOUT_HARD_CAP_MS = 15 * 60 * 1000;
+export const VERIFY_DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * pln#632 — engine-run verify command config, set by the loop OPENER at open (never by
+ * the agent under test — that is the determinism guarantee). The command is an argv
+ * ARRAY run with `shell:false` (no injection surface); an operator who needs a pipeline
+ * passes it explicitly as `['bash','-lc','npm test && npm run lint']` and owns that.
+ * When present, `bclaw_loop(intent='verify')` runs it and records a deterministic
+ * `verify_report`; absent, the loop falls back to the agent-narrated report unchanged.
+ */
+export const LoopVerifyConfigSchema = z.object({
+    command: z.array(z.string().min(1)).min(1),
+    timeout_ms: z.number().int().positive().max(VERIFY_TIMEOUT_HARD_CAP_MS).optional(),
 });
 export const LoopProtocolConfigSchema = z.object({
     review_mode: z.enum(REVIEW_MODES).optional(),
     iteration: LoopIterationSchema.optional(),
+    /** pln#632 — engine-run verify command (opener-provided; makes command_green real). */
+    verify: LoopVerifyConfigSchema.optional(),
     /**
      * pln#508 step 1 — protocol preset selector. When set (e.g. `'bootstrap'`),
      * the coordinate facade routes preset-specific behaviors (close hook,
@@ -139,6 +156,13 @@ export const LoopSlotSchema = z.object({
     claim_id: z.string().optional(),
     phase: z.string().optional(),
     status: z.enum(SLOT_STATUSES),
+    /**
+     * pln#630 PR2b-a (§13 R1) — pointer to the immutable turn-attempt record for
+     * the slot's CURRENT dispatch. Identity/evidence live on the attempt
+     * (`.brainclaw/loops/reservations/<turn_id>.json`), never overwritten on the
+     * reusable slot. Additive; wired onto the dispatch path in a later PR.
+     */
+    current_turn_id: z.string().optional(),
 });
 // ───────────────────────────────────────────────────────────────────────
 // pln#508 step 1 — bootstrap loop foundation: operator-interaction schemas
@@ -305,9 +329,29 @@ export const REF_BASED_ARTIFACT_TYPES = new Set([
  * is enforced. This preserves backward compatibility with proposal / critique
  * / revision / plan_draft / change_summary artifacts produced before pln#508.
  */
+/**
+ * pln#609 — implementation loop `verify_report` artifact body. Records the
+ * outcome of a verify command (tests/build/lint) for one execute↔verify
+ * iteration. `passed` is the single field the `command_green` iteration exit
+ * reads. Kept small (tails only) to fit LOOP_ARTIFACT_BODY_MAX_BYTES. In
+ * Increment 1 the report is produced by the verify turn (add_artifact); the
+ * engine-run execution seam (spawnSync, out of the loop lock) is Increment 2.
+ */
+export const VerifyReportBodySchema = z.object({
+    command: z.string().min(1),
+    exit_code: z.number().int().nullable(),
+    passed: z.boolean(),
+    duration_ms: z.number().int().nonnegative().optional(),
+    cwd: z.string().optional(),
+    timed_out: z.boolean().optional(),
+    stdout_tail: z.string().max(1024).optional(),
+    stderr_tail: z.string().max(1024).optional(),
+});
 export const KNOWN_ARTIFACT_BODY_SCHEMAS = {
     // inline JSON body: body = JSON.stringify({ ...fields per OperatorQuestionBodySchema })
     operator_question: OperatorQuestionBodySchema,
+    // inline JSON body: body = JSON.stringify({ ...fields per VerifyReportBodySchema })
+    verify_report: VerifyReportBodySchema,
     // inline JSON body: body = JSON.stringify({ ...fields per OperatorAnswerBodySchema })
     operator_answer: OperatorAnswerBodySchema,
     // ref-based: body = JSON.stringify({ ref, byte_count, sha256 })
@@ -560,6 +604,17 @@ export const LoopEventSchema = z.discriminatedUnion('kind', [
         input: z.string().optional(),
         retry_of: z.string().optional(),
     }),
+    // pln#630 PR2b-a (§13 R1/Q1) — journal breadcrumb that an immutable
+    // turn-attempt record was reserved for this dispatch. The authoritative
+    // record lives in `loops/reservations/<turn_id>.json`; this event lets a
+    // thread reader see the attempt existed without scanning that dir.
+    z.object({
+        ...LoopEventBaseShape,
+        kind: z.literal('turn_reserved'),
+        slot_id: z.string().min(1),
+        phase: z.string().min(1),
+        turn_id: z.string().min(1),
+    }),
     z.object({
         ...LoopEventBaseShape,
         kind: z.literal('turn_completed'),
@@ -726,23 +781,96 @@ export const DEFAULT_PROTOCOLS = {
         },
         stop_condition: { kind: 'artifact_produced', phase: 'synthesis', type: 'plan_draft' },
     },
+    // pln#609 — implementation loop v2. The loop ADDS to the dispatch pipeline
+    // what it lacked: a deterministic command_green gate + a bounded fix↔verify
+    // cycle + per-phase context sculpting. `bind` is an ENGINE action (bind
+    // plan+sequence and dispatch) not narration; execute↔verify iterates until
+    // the verify command is green (a passing verify_report this iteration) or
+    // the cycle cap is hit (→ handoff_ready with the red report → blocked).
     implementation: {
         phases: [
-            { name: 'sequence_build' },
-            { name: 'dispatch' },
-            { name: 'execute' },
-            { name: 'self_check' },
-            { name: 'handoff_ready' },
+            { name: 'bind', context_filter: ['plans', 'decisions', 'constraints', 'project_vision'] },
+            { name: 'execute', context_filter: ['decisions', 'constraints', 'traps', 'runtime_notes'] },
+            {
+                name: 'verify',
+                context_filter: ['traps', 'runtime_notes'],
+                // Cannot leave verify without having produced a verify_report THIS
+                // iteration — guards "narrated verify, didn't run it". Reuses the
+                // iteration-aware min_artifacts_by_type evaluator.
+                advance_gate: { kind: 'min_artifacts_by_type', type: 'verify_report', n: 1, scope: 'phase' },
+            },
+            { name: 'handoff_ready', context_filter: ['handoffs', 'plans'] },
         ],
-        stop_condition: { kind: 'artifact_produced', phase: 'handoff_ready', type: 'handoff' },
+        // execute ↔ verify bounded cycle; exit early when a passing verify_report
+        // exists in the current iteration (command_green).
+        iteration: {
+            cycle: ['execute', 'verify'],
+            max_iterations: 3,
+            exit_when: 'command_green',
+        },
+        // Mirrors review: handoff within budget → completed; cap exhausted without
+        // green → blocked (stopHitsMaxIterations).
+        stop_condition: {
+            kind: 'any',
+            conditions: [
+                { kind: 'artifact_produced', phase: 'handoff_ready', type: 'handoff' },
+                { kind: 'max_iterations', n: 3 },
+            ],
+        },
     },
+    // pln#628 PART 3 — research loop, ideation-shaped: investigate ↔ synthesize
+    // converges on a deliverable. NO max_iterations in the stop → research ALWAYS
+    // lands in `conclude` and completes with a synthesis (there is no "blocked"
+    // research outcome). exit_when=critic_signal: `synthesize` emits it when the
+    // question is judged answered (explicit sufficiency beats saturation-by-absence
+    // for open-ended research). Reuses existing machinery only.
     research: {
-        phases: [{ name: 'investigate' }, { name: 'synthesize' }],
-        stop_condition: { kind: 'manual' },
+        phases: [
+            {
+                name: 'investigate',
+                context_filter: ['plans', 'decisions', 'constraints', 'project_vision', 'candidates', 'runtime_notes', 'traps'],
+                // Don't synthesize an empty round: ≥1 finding gathered THIS iteration
+                // (iteration-aware phase scope) before advancing.
+                advance_gate: { kind: 'min_artifacts_by_type', type: 'finding', n: 1, scope: 'phase' },
+            },
+            { name: 'synthesize', context_filter: ['*'] },
+            { name: 'conclude', context_filter: ['*'] },
+        ],
+        iteration: { cycle: ['investigate', 'synthesize'], max_iterations: 3, exit_when: 'critic_signal' },
+        stop_condition: { kind: 'artifact_produced', phase: 'conclude', type: 'synthesis' },
     },
+    // pln#628 PART 3 — debug loop, implementation-shaped: "bug fixed" ⟺ "the
+    // reproducing command is now green" ⟺ a passing verify_report. hypothesize →
+    // isolate → fix repeats until the repro no longer reproduces (command_green)
+    // or the cycle cap is hit (→ handoff with the red report → blocked). Reuses
+    // command_green + verify_report; no new engine machinery.
     debug: {
-        phases: [{ name: 'reproduce' }, { name: 'hypothesize' }, { name: 'isolate' }, { name: 'fix' }],
-        stop_condition: { kind: 'manual' },
+        phases: [
+            {
+                name: 'reproduce',
+                context_filter: ['traps', 'runtime_notes', 'handoffs', 'plans'],
+                // Cannot start hypothesizing until a reliable repro exists.
+                advance_gate: { kind: 'artifact_produced', phase: 'reproduce', type: 'repro' },
+            },
+            { name: 'hypothesize', context_filter: ['decisions', 'constraints', 'traps', 'runtime_notes'] },
+            { name: 'isolate', context_filter: ['decisions', 'constraints', 'traps', 'runtime_notes'] },
+            {
+                name: 'fix',
+                context_filter: ['traps', 'runtime_notes', 'constraints'],
+                // Mirrors implementation's verify gate: cannot leave fix without having
+                // re-run the repro THIS iteration (iteration-aware phase scope).
+                advance_gate: { kind: 'min_artifacts_by_type', type: 'verify_report', n: 1, scope: 'phase' },
+            },
+            { name: 'handoff', context_filter: ['handoffs', 'plans'] },
+        ],
+        iteration: { cycle: ['hypothesize', 'isolate', 'fix'], max_iterations: 3, exit_when: 'command_green' },
+        stop_condition: {
+            kind: 'any',
+            conditions: [
+                { kind: 'artifact_produced', phase: 'handoff', type: 'handoff' },
+                { kind: 'max_iterations', n: 3 },
+            ],
+        },
     },
 };
 //# sourceMappingURL=types.js.map

package/dist/core/loops/verbs.js

@@ -3,6 +3,7 @@ import { nowISO } from '../ids.js';
 import { convergeAssignmentToTerminal } from '../assignments.js';
 import { writeProjectMdSafe } from './hooks/bootstrap-write.js';
 import { appendEvent, closeLoop, generateMutationId, getLoop, listLoopEvents, writeThreadFile, } from './store.js';
+import { commitViaIntent } from './commit-intent.js';
 import { LoopArtifactSchema, PAUSE_REASONS, } from './types.js';
 import { decideNextPhase, } from './iteration-engine.js';
 function nextSeq(loopId, cwd) {
@@ -416,6 +417,7 @@ export function turn(input, cwd) {
             phase: current.current_phase,
             assignment_id: input.assignment_id ?? slot.assignment_id,
             claim_id: input.claim_id ?? slot.claim_id,
+            current_turn_id: input.turn_id ?? slot.current_turn_id,
         }
         : slot);
     const next = {
@@ -519,9 +521,13 @@ export function complete_turn(input, cwd) {
         outcome,
         failure_reason: input.failure_reason,
     });
-    for (const event of events)
-        appendEvent(current.id, event, cwd);
-    writeThreadFile(next, cwd);
+    // pln#630 PR1b (dec#137) — stage the completion as ONE durable WAL intent,
+    // then apply it (journal fsync -> thread projection -> .applied marker).
+    // Crash-atomic + idempotent: a crash mid-write re-converges at the next
+    // lock-entry recovery. Replaces the former two-step appendEvent+writeThreadFile
+    // crash window that could lose the verdict or expose a projection ahead of the
+    // journal (codex r4). The events already carry their frozen seqs + event_ids.
+    commitViaIntent({ loop_id: current.id, base_version: current.version, events, thread_snapshot: next }, cwd);
     return next;
 }
 export function add_artifact(input, cwd) {

package/dist/core/loops/verify-command.js

@@ -0,0 +1,209 @@
+/**
+ * pln#632 — engine-run verify-command runner (pln#609 Increment 2).
+ *
+ * Makes the loop `command_green` gate DETERMINISTIC: brainclaw itself runs the
+ * configured verify command (tests/build/lint) and records a `verify_report`, instead
+ * of trusting an agent-narrated one. The iteration engine already READS a passing
+ * verify_report (iteration-engine.ts hasPassingVerifyReportInIteration); this module is
+ * the execution seam it referenced.
+ *
+ * SECURITY (the whole point of the runner):
+ *  - PROVENANCE: the command comes only from `thread.protocol.verify` (set by the loop
+ *    OPENER at open), never from the worker under test — that is the determinism
+ *    guarantee (a tested agent cannot fabricate green by supplying `['true']`).
+ *  - argv ARRAY, `shell:false` — no `;`/`&&`/`$()` injection surface. A pipeline is an
+ *    explicit `['bash','-lc','npm test && npm run lint']` the operator owns.
+ *  - ENV SANITIZATION: every `BRAINCLAW_*` (+ `BCLAW_PROMPT_FILE`) is stripped from the
+ *    child env so the spawned suite can't hit the REAL brainclaw store
+ *    (trap_agent_shell_env_contaminates_tests).
+ *  - BOUNDED: a timeout (→ passed:false, timed_out:true) + a maxBuffer cap.
+ *
+ * The long spawn runs OUT of the loop lock (two lock scopes with the spawn between),
+ * so a multi-minute test run never holds the lock past its deadline. Opt-out: no
+ * `protocol.verify` → a typed `unconfigured` result; the agent-narrated path is unchanged.
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { getLoop } from './store.js';
+import { withLoopLock } from './lock.js';
+import { add_artifact } from './verbs.js';
+import { artifactsInIteration } from './iteration-engine.js';
+import { VERIFY_DEFAULT_TIMEOUT_MS, LOOP_ARTIFACT_BODY_MAX_BYTES, } from './types.js';
+/** VerifyReportBodySchema caps stdout_tail/stderr_tail at 1024. */
+const TAIL_MAX = 1024;
+function tail(s) {
+    return s.length <= TAIL_MAX ? s : s.slice(s.length - TAIL_MAX);
+}
+/**
+ * The one security-critical function: spawnSync the verify command with `shell:false`,
+ * a SANITIZED env (all BRAINCLAW_* + BCLAW_PROMPT_FILE removed), a bounded timeout and
+ * maxBuffer. Timeout → passed:false, timed_out:true, exit_code:null. A spawn error
+ * (ENOENT — misconfigured command) → passed:false with the message in stderr_tail
+ * (stays RED, so the loop hits max_iterations → blocked, never a false green).
+ */
+export const defaultVerifyRunner = (config) => {
+    const env = { ...process.env };
+    for (const k of Object.keys(env)) {
+        if (k.startsWith('BRAINCLAW_') || k === 'BCLAW_PROMPT_FILE')
+            delete env[k];
+    }
+    const started = Date.now();
+    const r = spawnSync(config.command[0], config.command.slice(1), {
+        cwd: config.cwd,
+        env,
+        shell: false,
+        encoding: 'utf-8',
+        timeout: config.timeout_ms,
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    const duration_ms = Date.now() - started;
+    const err = r.error;
+    const stdout_tail = tail(r.stdout ?? '');
+    if (err?.code === 'ETIMEDOUT') {
+        return { exit_code: null, passed: false, timed_out: true, duration_ms, stdout_tail, stderr_tail: tail(r.stderr ?? '') };
+    }
+    if (err) {
+        // Could not RUN the command (ENOENT, EACCES, …) — red, with the reason.
+        return { exit_code: null, passed: false, timed_out: false, duration_ms, stdout_tail, stderr_tail: tail(String(err.message ?? err)) };
+    }
+    return {
+        exit_code: r.status,
+        passed: r.status === 0,
+        timed_out: false,
+        duration_ms,
+        stdout_tail,
+        stderr_tail: tail(r.stderr ?? ''),
+    };
+};
+/**
+ * Resolve the verify command for a loop. PR1: the loop-PROJECT cwd only (the
+ * lane-worktree cwd for a sequenced impl loop is a follow-up). Returns `unconfigured`
+ * when the loop opted out (no `protocol.verify`).
+ */
+export function resolveVerifyCommand(thread, cwd) {
+    const cfg = thread.protocol?.verify;
+    if (!cfg)
+        return { kind: 'unconfigured' };
+    return {
+        kind: 'ok',
+        config: {
+            command: cfg.command,
+            cwd: path.resolve(cwd ?? process.cwd()),
+            timeout_ms: cfg.timeout_ms ?? VERIFY_DEFAULT_TIMEOUT_MS,
+        },
+    };
+}
+/**
+ * pln#632 (review F2) — ensure the SERIALIZED body fits add_artifact's 4 KiB byte limit.
+ * Each tail is ≤1024 CHARS (schema-valid), but multibyte / ANSI output can make the
+ * JSON body exceed LOOP_ARTIFACT_BODY_MAX_BYTES *bytes* (a control char JSON-escapes to
+ * 6 bytes), which would make add_artifact throw and drop a green suite's report. Shrink
+ * the tails (halving) until the serialized body fits; last resort drops the tails.
+ */
+function fitBody(report) {
+    const size = (r) => Buffer.byteLength(JSON.stringify(r), 'utf8');
+    if (size(report) <= LOOP_ARTIFACT_BODY_MAX_BYTES)
+        return report;
+    for (let keep = 512; keep >= 1; keep = Math.floor(keep / 2)) {
+        const r = {
+            ...report,
+            stdout_tail: report.stdout_tail ? report.stdout_tail.slice(-keep) : undefined,
+            stderr_tail: report.stderr_tail ? report.stderr_tail.slice(-keep) : undefined,
+        };
+        if (size(r) <= LOOP_ARTIFACT_BODY_MAX_BYTES)
+            return r;
+    }
+    return { ...report, stdout_tail: undefined, stderr_tail: undefined };
+}
+export function buildVerifyReportBody(config, result) {
+    return fitBody({
+        command: config.command.join(' '),
+        exit_code: result.exit_code,
+        passed: result.passed,
+        duration_ms: result.duration_ms,
+        cwd: config.cwd,
+        timed_out: result.timed_out,
+        stdout_tail: result.stdout_tail || undefined,
+        stderr_tail: result.stderr_tail || undefined,
+    });
+}
+/** True when a verify_report already exists in this iteration (idempotency key = loop+iteration). */
+function hasVerifyReportForIteration(thread, iteration) {
+    return artifactsInIteration(thread, iteration).some((a) => a.type === 'verify_report');
+}
+/**
+ * Run the configured verify command and record a deterministic `verify_report` for the
+ * loop's CURRENT iteration/phase. Two lock scopes with the spawn BETWEEN them: scope 1
+ * reads the command + iteration + idempotency pre-check; the command runs OUT of the
+ * lock; scope 2 re-checks idempotency (a concurrent verify may have appended while we
+ * spawned) and appends via the existing `add_artifact` verb (which auto-stamps the
+ * iteration). Does NOT advance — the report is a fact; exiting the cycle stays a
+ * separate `advance` call by the driver.
+ */
+export function runVerify(input, cwd) {
+    const runner = input.runner ?? defaultVerifyRunner;
+    // --- Lock scope 1: read config + iteration; idempotency pre-check; snapshot. ---
+    const snapshot = withLoopLock({
+        cwd,
+        intent: 'verify',
+        agentId: input.actor,
+        scope: { kind: 'loop', loopId: input.loop_id },
+        work: () => {
+            const thread = getLoop(input.loop_id, cwd);
+            if (!thread)
+                throw new Error(`loop ${input.loop_id} not found`);
+            const resolved = resolveVerifyCommand(thread, cwd);
+            if (resolved.kind === 'unconfigured')
+                return { state: 'unconfigured', thread };
+            const iteration = thread.iteration_count;
+            if (hasVerifyReportForIteration(thread, iteration))
+                return { state: 'deduped', thread };
+            // Snapshot the iteration + phase we are about to verify. The command tests THIS
+            // iteration's working tree; the report must be attributed to it even if a
+            // concurrent advance bumps the loop's iteration while we spawn (review F1).
+            return { state: 'run', thread, config: resolved.config, iteration, phase: thread.current_phase };
+        },
+    });
+    if (snapshot.state === 'unconfigured')
+        return { thread: snapshot.thread, deduped: false, unconfigured: true };
+    if (snapshot.state === 'deduped')
+        return { thread: snapshot.thread, deduped: true };
+    // --- OUT OF LOCK: run the command (may take minutes). ---
+    const { config, iteration, phase } = snapshot;
+    const report = buildVerifyReportBody(config, runner(config));
+    // --- Lock scope 2: re-check idempotency (by SNAPSHOT iteration), then append. ---
+    return withLoopLock({
+        cwd,
+        intent: 'verify',
+        agentId: input.actor,
+        scope: { kind: 'loop', loopId: input.loop_id },
+        work: () => {
+            const thread = getLoop(input.loop_id, cwd);
+            if (!thread)
+                throw new Error(`loop ${input.loop_id} not found`);
+            // Dedup on the SNAPSHOT iteration — a report for the iteration we verified already
+            // landed (a concurrent verify won). Checking the snapshot (not the current)
+            // iteration is what makes this correct after a concurrent advance (review F1).
+            if (hasVerifyReportForIteration(thread, iteration)) {
+                return { thread, report, deduped: true };
+            }
+            const updated = add_artifact({
+                id: input.loop_id,
+                actor: input.actor,
+                artifact: {
+                    // Stamp the SNAPSHOT phase + iteration so the report is attributed to the
+                    // iteration whose code it actually tested — never a later iteration a
+                    // concurrent advance moved the loop to (which would be a FALSE green).
+                    phase,
+                    iteration,
+                    type: 'verify_report',
+                    body: JSON.stringify(report),
+                    produced_by: 'engine',
+                },
+            }, cwd);
+            const art = updated.artifacts[updated.artifacts.length - 1];
+            return { thread: updated, report, deduped: false, report_artifact_id: art?.artifact_id };
+        },
+    });
+}
+//# sourceMappingURL=verify-command.js.map

package/dist/core/messaging.js

@@ -50,18 +50,44 @@ function loadMessagesFromDir(dirPath) {
     }
     return items.sort((a, b) => a.created_at.localeCompare(b.created_at));
 }
+/**
+ * Hard cap on the inline body persisted per inbox message (pln#627 Phase B).
+ * Bodies above this are truncated at write time and flagged — the inbox must
+ * never again store a multi-hundred-KB persona/CoDev dump (root cause: one rfc
+ * message reached 960 KB). Large content belongs in a dedicated artifact store
+ * (Phase C), with the message carrying only a summary + pointer.
+ *
+ * Set ABOVE the largest *legitimate* message so real traffic is never
+ * corrupted: the loop brief assembler already bounds its memory bundle to
+ * DEFAULT_MAX_CHARS = 48 000 (brief-assembly.ts), and the coordinate dispatch
+ * envelope wraps that up to ~54 KB. 128 KB leaves ~2.4× headroom over that
+ * while still catching the ~960 KB dump class an order of magnitude below it.
+ */
+export const MAX_INLINE_MESSAGE_CHARS = 131_072;
+/** Truncate an over-cap body, appending a marker that names the original size. */
+function capMessageBody(text) {
+    const originalLength = text.length;
+    if (originalLength <= MAX_INLINE_MESSAGE_CHARS) {
+        return { text, truncated: false, originalLength };
+    }
+    const marker = `\n\n[truncated at write: ${originalLength} chars exceeded the ${MAX_INLINE_MESSAGE_CHARS}-char inbox cap; full body not stored inline — persist large content in an artifact store and reference it here]`;
+    const keep = Math.max(0, MAX_INLINE_MESSAGE_CHARS - marker.length);
+    return { text: text.slice(0, keep) + marker, truncated: true, originalLength };
+}
 export function sendMessage(input, cwd) {
     return mutate({ cwd }, () => {
         const { id, short_label } = generateIdWithLabel('inbox_messages', cwd);
         const timestamp = nowISO();
         const resolvedTo = resolveAgentAlias(input.to);
+        const capped = capMessageBody(input.text);
         const message = {
             id,
             short_label,
             from: input.from,
             to: resolvedTo,
             type: input.type,
-            text: input.text,
+            text: capped.text,
+            ...(capped.truncated ? { truncated_at_write: true, original_text_length: capped.originalLength } : {}),
             ref: input.ref,
             payload: input.payload,
             scope: input.scope,
@@ -83,14 +109,30 @@ export function sendMessage(input, cwd) {
         const dir = ensureAgentInboxDir(input.to, cwd);
         saveVersionedJsonFile('message', path.join(dir, `${id}.json`), message);
         commitMemoryChange(`message ${id} sent to ${resolvedTo}`, cwd);
-        return { id, shortLabel: short_label, to: resolvedTo, type: input.type };
+        return {
+            id,
+            shortLabel: short_label,
+            to: resolvedTo,
+            type: input.type,
+            ...(capped.truncated
+                ? { warning: `Message body truncated at write: ${capped.originalLength} chars exceeded the ${MAX_INLINE_MESSAGE_CHARS}-char inbox cap. Store large content in an artifact store and send a pointer instead.` }
+                : {}),
+        };
     });
 }
 /** Apply all inbox filters (status, type, thread_id, claim_id) to a message list. */
 function applyInboxFilters(messages, input) {
     let filtered = messages;
-    if (input.status)
+    if (input.status) {
         filtered = filtered.filter(m => m.status === input.status);
+    }
+    else if (!input.includeAll) {
+        // Default = actionable only (pln#627 Phase A): hide acknowledged + archived
+        // so a long tail of processed messages can't bury the live ones. Callers
+        // opt back into the full set with includeAll, or target a done status
+        // explicitly with `status`.
+        filtered = filtered.filter(m => m.status === 'pending' || m.status === 'read');
+    }
     if (input.type)
         filtered = filtered.filter(m => m.type === input.type);
     if (input.thread_id)
@@ -101,6 +143,17 @@ function applyInboxFilters(messages, input) {
     }
     return filtered;
 }
+/**
+ * Filter + order a directory's messages for a read (pln#627 Phase A).
+ * Ordered newest-first by created_at so a bounded page always serves the most
+ * recent messages, not the oldest debris — loadMessagesFromDir returns disk
+ * order (oldest-first, trp#291), which would otherwise make slice(0, limit)
+ * page through ancient processed messages first.
+ */
+function loadMessagesForRead(dir, input) {
+    const filtered = applyInboxFilters(loadMessagesFromDir(dir), input);
+    return filtered.sort((a, b) => b.created_at.localeCompare(a.created_at));
+}
 export function readInbox(input, cwd) {
     const dir = agentInboxDir(input.agent, cwd);
     // If markAsRead, do everything under a single lock to avoid race conditions.
@@ -108,7 +161,7 @@ export function readInbox(input, cwd) {
     if (input.markAsRead) {
         return mutate({ cwd }, () => {
             // Fresh read inside lock
-            const messages = applyInboxFilters(loadMessagesFromDir(dir), input);
+            const messages = loadMessagesForRead(dir, input);
             const total = messages.length;
             const offset = input.offset ?? 0;
             const limit = input.limit ?? 20;
@@ -127,7 +180,7 @@ export function readInbox(input, cwd) {
         });
     }
     // Read-only path: no lock needed
-    const messages = applyInboxFilters(loadMessagesFromDir(dir), input);
+    const messages = loadMessagesForRead(dir, input);
     const total = messages.length;
     const offset = input.offset ?? 0;
     const limit = input.limit ?? 20;