brainclaw 1.14.0 → 1.16.0

package/dist/core/entity-operations.js

@@ -6,10 +6,12 @@
  * Phase 3 slice 3b (pln_c6472192). Keeps imperative code where it lives
  * (per P6.2) — this module only routes.
  *
- * MVP wiring (this landing): plan, decision, constraint, trap,
- * runtime_note, candidate. Other entities throw
- * `EntityOperationUnsupportedError` with a pointer at the legacy tool
- * until later slices wire them in.
+ * Write-verb wiring is per entity. An unwired write verb picks its error from
+ * the registry's writePolicy (pln#625 Phase 2): a `system` entity (session,
+ * inbox_message, instruction, assignment, agent_run, action) reports the
+ * curated `SystemManagedError` naming its authorized path; an agent-ownable one
+ * (default) reports `EntityOperationUnsupportedError` ("not yet wired"). An
+ * unknown entity name is rejected at the front door with `UnknownEntityError`.
  */
 import path from 'node:path';
 import { loadState, mutateState } from './state.js';
@@ -17,6 +19,11 @@ import { archiveCandidate, listCandidates, loadCandidate, saveCandidate, } from
 import { addCrossProjectLink, removeCrossProjectLink, resolveCrossProjectLinks, } from './cross-project.js';
 import { findActiveClaimsForPlan, listClaims, loadClaim, logCascadeReleaseResult, markClaimStale, releaseClaimsCascade, releaseClaimWithCascade, saveClaim, } from './claims.js';
 import { listActionRequired } from './actions.js';
+import { listAgentIdentities } from './agent-registry.js';
+import { getCapabilityProfile, getSpawnableAgents } from './agent-capability.js';
+import { buildReputationSnapshot, toPublicReputationSummary } from './reputation.js';
+import { loadAllSessions } from './identity.js';
+import { loadInstructions } from './instructions.js';
 import { deleteAssignment, listAssignments, loadAssignment, saveAssignment, transitionAssignment } from './assignments.js';
 import { listAgentRuns } from './agentruns.js';
 import { reconcileAgentRun, reconcileDeadPidRunningAgentRunAtRead, TERMINAL_STATUSES } from './agentrun-reconciler.js';
@@ -26,9 +33,10 @@ import { createSequence, deleteSequence, listSequences, updateSequence, } from '
 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 { ENTITY_NAMES, ENTITY_REGISTRY, isValidTransition, } from './entity-registry.js';
 import { generateId } from './ids.js';
-import { CandidateTypeSchema, ConstraintCategorySchema, DecisionOutcomeSchema, MemoryVisibilitySchema, PlanTypeEnumSchema, PrioritySchema, RuntimeNoteTypeSchema, SequenceStatusSchema, SeveritySchema, } from './schema.js';
+import { mergeHandoffReview } from './handoff-review.js';
+import { CandidateTypeSchema, ConstraintCategorySchema, DecisionOutcomeSchema, HandoffContractSchema, HandoffReviewSchema, MemoryVisibilitySchema, PlanTypeEnumSchema, PrioritySchema, RuntimeNoteTypeSchema, SequenceStatusSchema, 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
@@ -88,12 +96,114 @@ export class EntityNotFoundError extends Error {
         this.name = 'EntityNotFoundError';
     }
 }
+/**
+ * Thrown when a write verb targets a `writePolicy:'system'` entity via a verb
+ * that is not agent-wired: the runtime owns these records, so this is a
+ * deliberate "not agent-writable" boundary, NOT a "coming soon" gap. Names the
+ * authorized path (writePolicyNote) so the caller knows where the write really
+ * happens. pln#625 Phase 2 — replaces the misleading "not yet wired. Use the
+ * legacy tool" for system entities.
+ */
+export class SystemManagedError extends Error {
+    constructor(entity, verb, note) {
+        super(
+        // Verb-scoped, not entity-scoped: some system entities have OTHER wired
+        // verbs (e.g. assignment transition/update), so don't claim the whole
+        // entity is unwritable — only that THIS verb is not an agent-facing
+        // grammar path for it.
+        `bclaw_${verb}(entity='${entity}'): ${entity} is system-managed — bclaw_${verb} is not available for it via the canonical grammar.`
+            + (note ? ` ${note}.` : ''));
+        this.name = 'SystemManagedError';
+    }
+}
+/**
+ * Pick the right "this write verb isn't available" error for an unwired entity,
+ * from the registry data (no per-switch string drift): a system-managed entity
+ * gets the SystemManagedError boundary; an agent-ownable one gets the
+ * "not yet wired" signal. Call this from a write verb's switch DEFAULT only —
+ * explicitly-wired verbs return before reaching it.
+ */
+function writeUnsupported(name, verb) {
+    const spec = ENTITY_REGISTRY[name];
+    if (spec?.writePolicy === 'system') {
+        return new SystemManagedError(name, verb, spec.writePolicyNote);
+    }
+    // Preserve the transition-specific hint the old default carried, so an
+    // agent-ownable-but-unwired transition (e.g. handoff) keeps its precise
+    // message rather than the generic "use the legacy tool" filler.
+    const hint = verb === 'transition' ? `Lifecycle transitions for ${name} not yet wired.` : undefined;
+    return new EntityOperationUnsupportedError(name, verb, hint);
+}
+/**
+ * Thrown when a canonical verb is called with an entity name that is not in the
+ * registry at all (e.g. bclaw_update(entity='agent')). Previously such a name
+ * reached `ENTITY_REGISTRY[name].updatable` and died on a raw TypeError
+ * ("Cannot read properties of undefined") — a leaked internal, not an
+ * operator-legible error. This front-door guard turns it into a curated message
+ * that lists the addressable entities (pln#625 Phase 1).
+ */
+export class UnknownEntityError extends Error {
+    constructor(entity, verb) {
+        super(`bclaw_${verb}(entity='${entity}') — unknown entity. ` +
+            // Deliberately "registered", not "supported": some listed entities are
+            // not yet wired for every verb (they return EntityOperationUnsupportedError,
+            // a different, already-curated signal). Don't imply all are writable here.
+            // NB agent is now a registered read-only entity (pln#625 Phase 2c): a write
+            // verb on it reaches the SystemManagedError boundary, not this front door.
+            `Registered entities (not all are wired for every verb yet): ${ENTITY_NAMES.join(', ')}.`);
+        this.name = 'UnknownEntityError';
+    }
+}
+/**
+ * Front-door guard for every canonical verb: reject an entity name that is not
+ * in the registry with a curated UnknownEntityError instead of letting it fall
+ * through to a raw property access. `name` is typed EntityName at the call
+ * sites, but the MCP layer passes an unvalidated string (entity is a free
+ * string on the published surface), so this runtime check is load-bearing.
+ */
+function assertKnownEntity(name, verb) {
+    if (!Object.prototype.hasOwnProperty.call(ENTITY_REGISTRY, name)) {
+        throw new UnknownEntityError(name, verb);
+    }
+}
 export class InvalidTransitionError extends Error {
     constructor(entity, from, to) {
         super(`Invalid transition for ${entity}: ${from} -> ${to}`);
         this.name = 'InvalidTransitionError';
     }
 }
+/**
+ * Canonical declaration of the bclaw_find/get FILTER grammar — the single
+ * source of truth for BOTH the MCP handler's validation and the governance
+ * fingerprint. Entity reachability lives in ENTITY_NAMES; this covers the
+ * filter contract, which is otherwise invisible to the published inputSchema
+ * (`filter` is an unconstrained object). Folded into the governance fingerprint
+ * (pln#625, Codex review of PR #82) so adding/renaming/re-scoping a filter key
+ * — or changing an accepted value — forces a changelog entry, closing the same
+ * blind-spot class as free-string `entity`.
+ */
+export const GRAMMAR_FILTER_CONTRACT = {
+    /** Accepted for ANY entity. */
+    common: [
+        'status', 'tag', 'tags', 'author', 'plan_id', 'source', 'auto_generated',
+        'limit', 'offset', 'includeLegacy', 'minAutoReflectConfidence',
+    ],
+    /** Keys accepted ONLY for the named entity (rejected with a validation_error elsewhere). */
+    entityScoped: {
+        agent_run: ['assignment_id', 'claim_id', 'message_id'],
+        agent: ['scope', 'includeReputation'],
+    },
+    /** Filter keys whose value is constrained to a fixed set. */
+    constrainedValues: {
+        scope: ['project', 'global'],
+    },
+    /**
+     * Filter keys whose value MUST be a boolean. Validated at the MCP front door
+     * so a stringy `"true"` is rejected loudly instead of silently coercing to a
+     * no-op (loadAgentsForRead requires a strict `=== true`). Codex review of #83.
+     */
+    booleanKeys: ['includeReputation'],
+};
 // ─── FIND ─────────────────────────────────────────────────────────────
 /**
  * Lazy reconciliation pass on agent_run reads (pln#503 phase 3.2).
@@ -140,7 +250,8 @@ function loadAgentRunsWithReconciliation(cwd) {
     return listAgentRuns(cwd);
 }
 export function listEntities(name, cwd, filter = {}) {
-    const all = loadAll(name, cwd);
+    assertKnownEntity(name, 'find');
+    const all = loadAll(name, cwd, filter);
     const fieldFiltered = applyFieldFilter(all, filter);
     const excludedLegacy = filter.includeLegacy === true
         ? 0
@@ -193,7 +304,101 @@ export function boundListResult(result, offset, charBudget = DEFAULT_FIND_CHAR_B
     }
     return bounded;
 }
-function loadAll(name, cwd) {
+/**
+ * Redacted read-only projection of an agent identity (pln#625 Phase 2c;
+ * refined by ideation loop lop_f8e8d18cb8c27ada). Shared by the grammar
+ * (find/get) AND bclaw_list_agents so redaction has ONE source of truth.
+ *
+ * Strict ALLOW-LIST — any field added to AgentIdentityDocument later stays
+ * hidden until someone deliberately projects it here:
+ *  - identity_key (private-ish key material: the PEM public_key) is dropped.
+ *  - `fingerprint` is the sha256(PEM) — the PUBLIC canonical key id, equal to
+ *    the cloud's agents.key_fingerprint — so it is exposed IN FULL: truncating
+ *    it added no confidentiality (a hash never reveals its preimage; the id is
+ *    public) and broke the whole point (matching a local key against the
+ *    256-bit remote fingerprint).
+ *  - `invoke` is intentionally NOT projected: it is populated by no writer and
+ *    read by no spawn path (buildInvokeCommand uses the capability profile, not
+ *    identity.invoke), so exposing it was dead surface — and it would leak
+ *    invoke.command (spawn flags, possibly tokens) verbatim.
+ * `short_label` mirrors agent_name so the generic getEntity matcher resolves an
+ * agent by id OR name (same trick as session's session_id→id alias).
+ */
+export function projectAgentForRead(doc) {
+    return {
+        id: doc.agent_id,
+        short_label: doc.agent_name,
+        name: doc.agent_name,
+        kind: doc.kind,
+        trust_level: doc.trust_level,
+        capabilities: doc.capabilities,
+        fingerprint: doc.identity_key?.fingerprint,
+        model: doc.model,
+        context_profile: doc.context_profile,
+        created_at: doc.created_at,
+    };
+}
+/**
+ * Catalog-only stub for a spawnable agent that is NOT in this project's
+ * registry (scope='global' only). It has no identity document, so only the
+ * name + dispatchability are known.
+ */
+function projectCatalogAgentForRead(name) {
+    return {
+        id: null,
+        short_label: name,
+        name,
+        kind: null,
+        trust_level: null,
+        capabilities: [],
+        dispatchable: true,
+        registered: false,
+    };
+}
+/**
+ * Load agents for a read (pln#625 Phase 2c, hybrid scope from lop_f8e8d18cb8c27ada).
+ * Default scope = the CURRENT PROJECT's registry (`.brainclaw/agents`, exactly
+ * what `list-agents` reads — there is NO global registry on disk). scope='global'
+ * additionally unions the static dispatchable catalog (getSpawnableAgents) and
+ * annotates each entry with `dispatchable` (canBeSpawnedCli) + `registered`
+ * (present in this project's registry) — the honest inventory a coordinator
+ * needs, since bclaw_dispatch resolves candidates from that catalog, NOT from
+ * the project registry.
+ */
+function loadAgentsForRead(cwd, filter) {
+    // Opt-in reputation join (pln#625 — folds the sole capability bclaw_list_agents
+    // had that find(agent) lacked, so that tool can be retired). Keyed by agent_id,
+    // which the projection exposes as `id`; catalog-only agents carry no reputation.
+    const reputationById = filter?.includeReputation === true
+        ? new Map((buildReputationSnapshot(cwd).agents ?? []).map((a) => [a.agent_id ?? a.key, toPublicReputationSummary(a)]))
+        : undefined;
+    const project = (doc) => {
+        const row = projectAgentForRead(doc);
+        if (reputationById)
+            row.reputation = reputationById.get(String(row.id));
+        return row;
+    };
+    const registered = listAgentIdentities(cwd).map(project);
+    const scope = typeof filter?.scope === 'string' ? filter.scope : 'project';
+    if (scope !== 'global')
+        return registered;
+    const byName = new Map();
+    for (const a of registered) {
+        a.registered = true;
+        a.dispatchable = getCapabilityProfile(String(a.name))?.runtime.canBeSpawnedCli ?? false;
+        byName.set(String(a.name), a);
+    }
+    for (const { name } of getSpawnableAgents()) {
+        const existing = byName.get(name);
+        if (existing) {
+            existing.dispatchable = true;
+            continue;
+        }
+        byName.set(name, projectCatalogAgentForRead(name));
+    }
+    return [...byName.values()];
+}
+function loadAll(name, cwd, filter) {
     switch (name) {
         case 'plan': return loadState(cwd).plan_items;
         case 'decision': return loadState(cwd).recent_decisions;
@@ -207,7 +412,21 @@ function loadAll(name, cwd) {
         case 'action': return listActionRequired(cwd);
         case 'assignment': return listAssignments(cwd);
         case 'agent_run': return loadAgentRunsWithReconciliation(cwd);
+        // pln#625 Phase 2c — agent is READ-ONLY via the grammar, redacted projection.
+        // Default scope = current project's registry; filter.scope='global' unions
+        // the dispatchable catalog. See loadAgentsForRead.
+        case 'agent': return loadAgentsForRead(cwd, filter);
         case 'cross_project_link': return resolveCrossProjectLinks(cwd);
+        // pln#625 Phase 2 — wire the previously-unwired reads.
+        case 'step': return loadState(cwd).plan_items.flatMap((p) => p.steps ?? []);
+        // session is keyed by session_id, not id — alias it so get/find match on either.
+        case 'session': return loadAllSessions(cwd).map((s) => ({ ...s, id: s.session_id }));
+        case 'instruction': return loadInstructions(cwd);
+        case 'inbox_message':
+            // Messages are inherently per-agent; the canonical find/get has no agent
+            // scope and there is no cross-agent aggregate loader. Route reads to the
+            // dedicated per-agent tool instead of inventing a misleading global list.
+            throw new EntityOperationUnsupportedError(name, 'find', 'Messages are per-agent — read them via bclaw_read_inbox(agent=…), not the canonical grammar.');
         default:
             throw new EntityOperationUnsupportedError(name, 'find');
     }
@@ -258,6 +477,7 @@ function applyPaging(items, filter) {
 }
 // ─── GET ───────────────────────────────────────────────────────────────
 export function getEntity(name, idOrShortLabel, cwd) {
+    assertKnownEntity(name, 'get');
     if (name === 'cross_project_link') {
         const links = resolveCrossProjectLinks(cwd);
         const hit = links.find((l) => l.name === idOrShortLabel ||
@@ -277,6 +497,7 @@ export function getEntity(name, idOrShortLabel, cwd) {
 }
 // ─── CREATE ────────────────────────────────────────────────────────────
 export function createEntity(name, data, cwd) {
+    assertKnownEntity(name, 'create');
     switch (name) {
         case 'plan': {
             // Explicit field whitelist + required-author check brings plan create in line
@@ -403,12 +624,23 @@ export function createEntity(name, data, cwd) {
             return { entity: name, id: link.name ?? link.path };
         }
         default:
-            throw new EntityOperationUnsupportedError(name, 'create');
+            throw writeUnsupported(name, 'create');
     }
 }
 // ─── UPDATE ────────────────────────────────────────────────────────────
 export function updateEntity(name, id, patch, cwd) {
+    assertKnownEntity(name, 'update');
     const spec = ENTITY_REGISTRY[name];
+    // An entity with NO updatable fields is not patchable via the grammar at all,
+    // so route to the curated boundary (SystemManagedError for a system entity,
+    // "not yet wired" otherwise) rather than the misleading "Fields not updatable
+    // … use bclaw_transition" — which assumes a lifecycle the entity may not have
+    // (e.g. agent, inbox_message have neither updatable fields nor transitions).
+    // Entities with a non-empty updatable list (incl. the wired case 'assignment'
+    // below) are unaffected. pln#625 Phase 2c.
+    if (spec.updatable.length === 0) {
+        throw writeUnsupported(name, 'update');
+    }
     const invalidFields = Object.keys(patch).filter((field) => !spec.updatable.includes(field));
     if (invalidFields.length > 0) {
         throw new Error(`Fields not updatable on ${name}: [${invalidFields.join(', ')}]. ` +
@@ -523,12 +755,75 @@ export function updateEntity(name, id, patch, cwd) {
             });
             return { entity: name, id: merged.name ?? merged.path };
         }
+        case 'handoff': {
+            // pln#625 Phase 3 — wire the handoff update path (previously unwired: the
+            // field check passed for narrative/tags but the switch fell to the default
+            // "not yet wired"). Restores the review-state write capability lost when
+            // update_handoff was removed at v1.0 — an agent can now write a review
+            // verdict via bclaw_update(entity='handoff', data={review:{verdict,…}}).
+            // review/contract are validated against their Zod schemas and MERGED onto
+            // the record (same field-merge semantics as the review loop's core
+            // applyHandoffUpdates); narrative/tags are set directly.
+            // Validate on the WRITE path with .strict() so an unknown key (e.g. a
+            // `review_verdict` typo that Zod would otherwise silently strip) is
+            // rejected loudly, and require at least one recognized field so an empty
+            // `{}` patch can't masquerade as a successful no-op (Codex review of #84).
+            // The base read schema stays non-strict — historical handoffs may carry
+            // extra fields.
+            let parsedReview;
+            let parsedContract;
+            if (patch.review !== undefined) {
+                const r = HandoffReviewSchema.strict().safeParse(patch.review);
+                if (!r.success) {
+                    throw new Error(`Invalid handoff.review: ${r.error.issues.map((i) => i.message).join('; ')}`);
+                }
+                if (Object.keys(r.data).length === 0) {
+                    throw new Error('handoff.review patch has no recognized fields (nothing to update).');
+                }
+                parsedReview = r.data;
+            }
+            if (patch.contract !== undefined) {
+                const c = HandoffContractSchema.strict().safeParse(patch.contract);
+                if (!c.success) {
+                    throw new Error(`Invalid handoff.contract: ${c.error.issues.map((i) => i.message).join('; ')}`);
+                }
+                if (Object.keys(c.data).length === 0) {
+                    throw new Error('handoff.contract patch has no recognized fields (nothing to update).');
+                }
+                parsedContract = c.data;
+            }
+            mutateState((state) => {
+                const item = state.open_handoffs.find((h) => h.id === id);
+                if (!item)
+                    throw new EntityNotFoundError(name, id);
+                // Tip guard (mirrors transition): a superseded handoff is a frozen
+                // tombstone — refuse to mutate it, point at the tip.
+                if (typeof item.superseded_by === 'string' && item.superseded_by) {
+                    throw new Error(`Handoff '${id}' was superseded by ${item.superseded_by} and is an immutable tombstone. `
+                        + `Update the current tip (${item.superseded_by}) instead.`);
+                }
+                if (patch.narrative !== undefined)
+                    item.narrative = patch.narrative;
+                if (patch.tags !== undefined)
+                    item.tags = patch.tags;
+                // Review merge + reviewed_at stamping via the shared core helper (single
+                // source of truth with applyHandoffUpdates — no drift between paths).
+                if (parsedReview !== undefined) {
+                    item.review = mergeHandoffReview(item.review, parsedReview);
+                }
+                if (parsedContract !== undefined) {
+                    item.contract = { ...(item.contract ?? {}), ...parsedContract };
+                }
+            }, cwd);
+            return { entity: name, id };
+        }
         default:
-            throw new EntityOperationUnsupportedError(name, 'update');
+            throw writeUnsupported(name, 'update');
     }
 }
 // ─── REMOVE ────────────────────────────────────────────────────────────
 export function removeEntity(name, id, cwd, purge = false) {
+    assertKnownEntity(name, 'remove');
     switch (name) {
         case 'plan': {
             deletePlan(id, cwd);
@@ -596,10 +891,11 @@ export function removeEntity(name, id, cwd, purge = false) {
             return { entity: name, id, archived: true, purged: false };
         }
         default:
-            throw new EntityOperationUnsupportedError(name, 'remove');
+            throw writeUnsupported(name, 'remove');
     }
 }
 export function transitionEntity(name, id, to, cwd, _reason, auth) {
+    assertKnownEntity(name, 'transition');
     const spec = ENTITY_REGISTRY[name];
     if (!spec.statusField) {
         throw new Error(`${name} has no lifecycle (statusField is undefined)`);
@@ -704,8 +1000,35 @@ export function transitionEntity(name, id, to, cwd, _reason, auth) {
             // isValidTransition already excluded every other target — belt-and-braces:
             throw new InvalidTransitionError(name, from, to);
         }
+        case 'handoff': {
+            // pln#625 Phase 2a — wire the handoff lifecycle (open→accepted|closed,
+            // accepted→closed; the matrix is enforced by isValidTransition above).
+            // This also repairs `brainclaw stale resolve <handoff-id>`, which routes
+            // through bclaw_transition(entity='handoff') and previously fell to the
+            // "not yet wired" default (trp_ed1a21eb).
+            //
+            // Tip guard: a handoff carrying `superseded_by` is the frozen original a
+            // correction replaced — correctHandoff leaves it immutable and pushes the
+            // correction as the new tip (mcp-write-entities.ts:356). Transitioning a
+            // superseded record would mutate frozen history, so refuse it and point at
+            // the tip, mirroring correctHandoff's own guard.
+            if (typeof current.superseded_by === 'string' && current.superseded_by) {
+                throw new Error(`Handoff '${id}' was superseded by ${current.superseded_by} and is an immutable tombstone. `
+                    + `Transition the current tip (${current.superseded_by}) instead.`);
+            }
+            mutateState((state) => {
+                const item = state.open_handoffs.find((h) => h.id === id);
+                if (!item)
+                    throw new EntityNotFoundError(name, id);
+                item[statusField] = to;
+            }, cwd);
+            return { entity: name, id, from, to, side_effects: sideEffects };
+        }
         default:
-            throw new EntityOperationUnsupportedError(name, 'transition', `Lifecycle transitions for ${name} not yet wired.`);
+            // pln#625 Phase 2 — system-managed entities (action/agent_run) report the
+            // curated "system-managed" boundary; agent-ownable-but-unwired ones keep
+            // the "not yet wired" signal.
+            throw writeUnsupported(name, 'transition');
     }
 }
 // ─── Helpers ──────────────────────────────────────────────────────────

package/dist/core/entity-registry.js

@@ -17,7 +17,7 @@
  *    patch. Non-listed fields are set at create time or via a
  *    transition — never by plain update.
  */
-import { CandidateSchema, ClaimSchema, ConstraintSchema, CrossProjectLinkSchema, CurrentSessionStateSchema, DecisionSchema, HandoffSchema, InboxMessageSchema, InstructionEntrySchema, PlanItemSchema, PlanStepSchema, RuntimeNoteSchema, SequenceSchema, TrapSchema, AssignmentSchema, AgentRunSchema, ActionRequiredSchema, } from './schema.js';
+import { CandidateSchema, ClaimSchema, ConstraintSchema, CrossProjectLinkSchema, CurrentSessionStateSchema, DecisionSchema, HandoffSchema, InboxMessageSchema, InstructionEntrySchema, PlanItemSchema, PlanStepSchema, RuntimeNoteSchema, SequenceSchema, TrapSchema, AssignmentSchema, AgentRunSchema, ActionRequiredSchema, AgentIdentityDocumentSchema, } from './schema.js';
 /** Canonical plan lifecycle. */
 const plan = {
     name: 'plan',
@@ -80,6 +80,8 @@ const claim = {
 const session = {
     name: 'session',
     shortLabelPrefix: 'sess',
+    writePolicy: 'system',
+    writePolicyNote: 'sessions are opened/refreshed by the runtime (bclaw_work + the session lifecycle), not written via the grammar',
     schema: CurrentSessionStateSchema,
     updatable: ['last_seen_at'],
     transitions: {},
@@ -91,7 +93,12 @@ const handoff = {
     name: 'handoff',
     shortLabelPrefix: 'hnd',
     schema: HandoffSchema,
-    updatable: ['narrative', 'tags'],
+    // pln#625 Phase 3 — review + contract are updatable so an agent can write a
+    // review verdict through the grammar (bclaw_update(entity='handoff',
+    // data={review:{…}})), restoring the capability lost when update_handoff was
+    // removed at v1.0. Validated against HandoffReviewSchema/HandoffContractSchema
+    // in updateEntity.
+    updatable: ['narrative', 'tags', 'review', 'contract'],
     statusField: 'status',
     transitions: {
         open: ['accepted', 'closed'],
@@ -225,6 +232,8 @@ const sequence = {
 const inbox_message = {
     name: 'inbox_message',
     shortLabelPrefix: 'msg',
+    writePolicy: 'system',
+    writePolicyNote: 'messages are created by bclaw_send_message and transitioned by bclaw_ack_message / bclaw_read_inbox',
     schema: InboxMessageSchema,
     updatable: [],
     statusField: 'status',
@@ -244,6 +253,8 @@ const inbox_message = {
 const instruction = {
     name: 'instruction',
     shortLabelPrefix: 'ins',
+    writePolicy: 'system',
+    writePolicyNote: 'instructions are managed via project setup / config (the instruction layer), not the grammar',
     schema: InstructionEntrySchema,
     updatable: ['text', 'tags', 'active'],
     transitions: {},
@@ -259,6 +270,8 @@ const instruction = {
 const assignment = {
     name: 'assignment',
     shortLabelPrefix: 'asgn',
+    writePolicy: 'system',
+    writePolicyNote: 'assignments are created by dispatch (bclaw_coordinate / bclaw_dispatch) and advanced via bclaw_assignment_update or the reconciler (transition IS wired)',
     schema: AssignmentSchema,
     updatable: ['description', 'status_reason', 'tags'],
     statusField: 'status',
@@ -286,6 +299,8 @@ const assignment = {
 const agent_run = {
     name: 'agent_run',
     shortLabelPrefix: 'run',
+    writePolicy: 'system',
+    writePolicyNote: 'agent_runs are created and reconciled by the dispatch/execution layer, not written via the grammar',
     schema: AgentRunSchema,
     updatable: ['output_summary', 'error_summary'],
     statusField: 'status',
@@ -302,23 +317,70 @@ const agent_run = {
         'running->failed': ['timestamp:completed_at', 'event:agent_run_failed'],
     },
 };
-/** Action — required follow-up item. */
+/**
+ * Action — runtime pause/resume record (approval / user_input / clarification /
+ * plan_approval). Created `pending` by the runtime; resolved via
+ * src/core/actions.ts:resolveAction (outcome resolved|rejected|cancelled) or
+ * swept to `expired` on read past its TTL. resolveAction refuses any non-pending
+ * action, so `pending` is the ONLY non-terminal state.
+ *
+ * pln#625 Phase 0 — this spec previously declared open/in_progress/completed/
+ * dismissed, NONE of which are valid ActionRequired statuses
+ * (ActionRequiredStatusSchema = pending/resolved/rejected/cancelled/expired),
+ * and `updatable` named description/priority which are not fields on
+ * ActionRequiredSchema. Any canonical transition built on the old matrix would
+ * have been dead-on-arrival (InvalidTransitionError / schema reject). The
+ * EntitySpec↔Zod consistency test now pins the FSM to the persisted enum so it
+ * can never silently drift again.
+ *
+ * NB (pln#625 Phase 2): action is writePolicy:'system', so update/remove/
+ * transition(action) now return the curated SystemManagedError (managed via
+ * resolveAction / bclaw_assignment_action), not "not yet wired". If a later
+ * phase DOES wire an agent-facing update(action), it MUST gate patches to
+ * status==='pending' (patching title/prompt on a resolved action would rewrite
+ * the record of what a human already approved).
+ */
 const action = {
     name: 'action',
     shortLabelPrefix: 'act',
+    writePolicy: 'system',
+    writePolicyNote: 'actions are raised by the runtime and resolved via bclaw_assignment_action (resolveAction), not written via the grammar',
     schema: ActionRequiredSchema,
-    updatable: ['description', 'priority'],
+    updatable: ['title', 'prompt', 'tags'],
     statusField: 'status',
     transitions: {
-        open: ['in_progress', 'completed', 'dismissed'],
-        in_progress: ['completed', 'dismissed'],
+        pending: ['resolved', 'rejected', 'cancelled', 'expired'],
     },
-    terminal: ['completed', 'dismissed'],
+    terminal: ['resolved', 'rejected', 'cancelled', 'expired'],
     sideEffects: {
-        'open->completed': ['audit:action_completed'],
-        'in_progress->completed': ['audit:action_completed'],
+        'pending->resolved': ['timestamp:resolved_at', 'audit:action_resolved', 'sync:agent_run_resume', 'sync:assignment_resume'],
+        'pending->rejected': ['timestamp:resolved_at', 'audit:action_resolved', 'sync:agent_run_cancel', 'sync:assignment_fail'],
+        'pending->cancelled': ['timestamp:resolved_at', 'audit:action_resolved', 'sync:agent_run_cancel', 'sync:assignment_fail'],
+        // The expire sweep (actions.ts) sets only status + updated_at — it does NOT
+        // stamp resolved_at (that is resolveActionRequired's job on the resolve/
+        // reject/cancel edges), so this edge intentionally carries no timestamp tag.
+        'pending->expired': ['audit:action_expired', 'sync:agent_run_timeout', 'sync:assignment_fail'],
     },
 };
+/**
+ * Agent — identity-registry entry (agents/ dir). READ-ONLY through the grammar
+ * (pln#625 Phase 2c): find/get return a REDACTED projection — identity_key and
+ * invoke.env are never surfaced, the key fingerprint is truncated. Agents are
+ * registered/managed by bclaw_setup / enable-agent (the agent registry), NOT
+ * the grammar, so writePolicy:'system' routes every write verb to the curated
+ * SystemManagedError boundary. Stateless: no lifecycle, no transitions.
+ */
+const agent = {
+    name: 'agent',
+    shortLabelPrefix: 'agt',
+    schema: AgentIdentityDocumentSchema,
+    updatable: [],
+    writePolicy: 'system',
+    writePolicyNote: 'agents are registered/managed via bclaw_setup / enable-agent (the agent registry); the grammar exposes only a redacted read-only view via bclaw_find/get',
+    transitions: {},
+    terminal: [],
+    sideEffects: {},
+};
 /**
  * Cross-project link — federation peer entry stored in config.yaml
  * (cross_project_links). Stateless: identified by `name`, no lifecycle.
@@ -341,6 +403,7 @@ export const ENTITY_REGISTRY = {
     decision, constraint, trap, candidate, runtime_note, sequence,
     inbox_message, instruction,
     assignment, agent_run, action,
+    agent,
     cross_project_link,
 };
 export const ENTITY_NAMES = Object.keys(ENTITY_REGISTRY);