@event4u/agent-config 14.19.0 → 14.21.0

package/src/scripts/_lib/self_repair_store.ts

@@ -12,12 +12,16 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import {
+    ACTIVE_STATUSES,
     creationCapReached,
     type DefectFinding,
     type DefectRecord,
     type DefectSource,
     fingerprint,
+    isWellFormedTarget,
     mergeRecord,
+    parseTarget,
+    validateRecord,
 } from './self_repair.js';
 
 export const STORE_REL = path.join('agents', 'runtime', 'self-repair');
@@ -48,7 +52,16 @@ export function readRecord(root: string, fp: string): DefectRecord | null {
     }
 }
 
+/**
+ * Write one record. VALIDATES first — a `parked` record with no wake condition
+ * or a malformed target never reaches the store, because a store that accepts
+ * an unwakeable park has the same defect the park was supposed to fix.
+ */
 export function writeRecord(root: string, record: DefectRecord): void {
+    const problems = validateRecord(record);
+    if (problems.length > 0) {
+        throw new Error(`refusing to write an invalid record: ${problems.join('; ')}`);
+    }
     const dir = storeDir(root);
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(
@@ -71,7 +84,7 @@ export function listRecords(root: string): DefectRecord[] {
         // The overflow counter shares the directory and the extension but is not
         // a record. `isRecord` would reject it anyway; naming it here keeps the
         // exclusion intentional rather than incidental.
-        if (!n.endsWith('.json') || n === OVERFLOW_FILE) {
+        if (!n.endsWith('.json') || n === OVERFLOW_FILE || n === TARGET_INDEX_FILE) {
             continue;
         }
         const rec = readRecord(root, n.slice(0, -'.json'.length));
@@ -83,8 +96,16 @@ export function listRecords(root: string): DefectRecord[] {
     return out;
 }
 
+/**
+ * The records still in the queue. Since the status enum widened past
+ * `open | released`, "still queued" is `open` OR `candidate` — a record someone
+ * accepted but has not yet acted on has not left the queue, and a `declined`,
+ * `superseded`, `actioned` or `parked` one has.
+ */
 export function openRecords(root: string): DefectRecord[] {
-    return listRecords(root).filter((r) => r.status === 'open');
+    return listRecords(root).filter((r) =>
+        (ACTIVE_STATUSES as readonly string[]).includes(r.status),
+    );
 }
 
 /**
@@ -134,29 +155,60 @@ export function upsertFinding(
     root: string,
     finding: DefectFinding,
     now: string,
+    // The tree the targets resolve against. Defaults to the store root, which
+    // is the production case (both are the repo). A test sandboxes the STORE in
+    // a tmp dir while still resolving `rule:scope-control` against the real
+    // tree, and folding the two roots together would make that untestable.
+    opts?: { treeRoot?: string },
 ): DefectRecord | null {
     const fp = fingerprint(finding.defect_class, finding.evidence);
+    // Targets are resolved against the tree HERE, at the write boundary: the
+    // pure half cannot read the filesystem, and validating anywhere later would
+    // mean a dangling id had already been stored.
+    const split = partitionTargets(opts?.treeRoot ?? root, [
+        ...(finding.target ?? []),
+        ...(finding.proposes ?? []),
+    ]);
+    const resolved: DefectFinding = {
+        ...finding,
+        ...(split.target.length > 0 ? { target: split.target } : {}),
+        ...(split.proposes.length > 0 ? { proposes: split.proposes } : {}),
+    };
+    if (split.target.length === 0) delete resolved.target;
+    if (split.proposes.length === 0) delete resolved.proposes;
     const existing = readRecord(root, fp);
     // The fold path never consults the cap: a fingerprint already in the store
     // adds no file, so capping it would silence a tracked defect for no bound.
-    if (existing === null && creationCapReached(listRecords(root), finding, now)) {
-        bumpOverflow(root, finding.source, now);
+    if (existing === null && creationCapReached(listRecords(root), resolved, now)) {
+        bumpOverflow(root, resolved.source, now);
         return null;
     }
-    const merged = mergeRecord(existing, finding, now);
+    const merged = mergeRecord(existing, resolved, now);
     writeRecord(root, merged);
     return merged;
 }
 
-/** Mark a record released (a PR or issue now carries it). */
+/**
+ * Mark a record released — a PR or issue now carries it.
+ *
+ * The stored status is `actioned`, not the retired `released`: releasing IS the
+ * action, and the widened enum has no separate slot for it. The function name
+ * is kept because the CALLER's event is still "a release happened".
+ */
 export function markReleased(root: string, fp: string, now: string): DefectRecord | null {
     const rec = readRecord(root, fp);
     if (rec === null) {
         return null;
     }
     // A successful release supersedes any earlier failed attempts.
-    const next: DefectRecord = { ...rec, status: 'released', last_seen: now };
+    const next: DefectRecord = {
+        ...rec,
+        status: 'actioned',
+        resolution: rec.resolution ?? 'released — a pull request or issue now carries this record',
+        last_seen: now,
+    };
     delete next.release_errors;
+    delete next.parked_until;
     writeRecord(root, next);
     return next;
 }
@@ -186,3 +238,217 @@ export function attachReleaseErrors(
     writeRecord(root, next);
     return next;
 }
+
+// target resolution
+//
+// `suggested_surface` is free text, so nothing could join a record to the asset
+// it is about. A `target` entry is `<kind>:<id>` from a closed vocabulary AND it
+// is resolved against the tree at WRITE time — an unresolvable entry is not
+// rejected (a record proposing an asset that should exist is real information)
+// and is not silently accepted either (a dangling id looks joined and joins to
+// nothing). It is moved to `proposes`, where a reader can see it for what it is.
+
+/** Where each target kind lives in the source tree. */
+function _targetExists(root: string, kind: string, id: string): boolean {
+    if (kind === 'rule') {
+        return fs.existsSync(path.join(root, 'src', 'rules', `${id}.md`));
+    }
+    if (kind === 'skill') {
+        return fs.existsSync(path.join(root, 'src', 'skills', id, 'SKILL.md'));
+    }
+    if (kind === 'command') {
+        return _commandIds(root).has(id);
+    }
+    if (kind === 'hook') {
+        return _concernIds(root).has(id);
+    }
+    return false;
+}
+
+/**
+ * Command ids, read from the pack tree: every `command.md` under
+ * `src/domains/<pack>/…` contributes the name of its containing directory, plus
+ * the `parent-child` form a clustered command is referred to by.
+ */
+function _commandIds(root: string): ReadonlySet<string> {
+    const out = new Set<string>();
+    const base = path.join(root, 'src', 'domains');
+    const walk = (dir: string, trail: string[]): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (ent.isDirectory()) {
+                walk(path.join(dir, ent.name), [...trail, ent.name]);
+            } else if (ent.name === 'command.md' && trail.length > 0) {
+                out.add(trail[trail.length - 1] as string);
+                if (trail.length > 1) {
+                    out.add(trail.slice(-2).join('-'));
+                }
+            }
+        }
+    };
+    walk(base, []);
+    return out;
+}
+
+/**
+ * Hook-concern ids, read from the compiled manifest rather than re-parsing the
+ * YAML: `hook_manifest.json` is the artifact the dispatcher itself reads, so a
+ * concern that resolves here is a concern that actually exists at runtime.
+ */
+function _concernIds(root: string): ReadonlySet<string> {
+    try {
+        const raw = fs.readFileSync(
+            path.join(root, 'src', 'scripts', 'hook_manifest.json'),
+            'utf-8',
+        );
+        const parsed = JSON.parse(raw) as { manifest?: { concerns?: Record<string, unknown> } };
+        return new Set(Object.keys(parsed.manifest?.concerns ?? {}));
+    } catch {
+        return new Set<string>();
+    }
+}
+
+/**
+ * Split a caller's target list into the entries that resolve in the tree and
+ * the entries that do not. Malformed entries go to `proposes` too — a string
+ * that is not `<kind>:<id>` cannot be resolved, and dropping it would lose the
+ * observation.
+ */
+export function partitionTargets(
+    root: string,
+    values: readonly string[],
+): { target: string[]; proposes: string[] } {
+    const target: string[] = [];
+    const proposes: string[] = [];
+    for (const raw of values) {
+        const value = raw.trim();
+        if (value === '') continue;
+        const parsed = isWellFormedTarget(value) ? parseTarget(value) : null;
+        if (parsed !== null && _targetExists(root, parsed.kind, parsed.id)) {
+            if (!target.includes(value)) target.push(value);
+        } else if (!proposes.includes(value)) {
+            proposes.push(value);
+        }
+    }
+    return { target, proposes };
+}
+
+// per-target occurrence index
+//
+// `occurrences` counts a FINGERPRINT, which is class plus normalised evidence
+// shape — so two different manifestations of one rule's weakness are two
+// records with one occurrence each, and the third-recurrence escalation stated
+// in `skill-improvement-pipeline` had nothing that could ever establish a third
+// recurrence. This is a DERIVED read over the record files: regenerable,
+// byte-stable, and gitignored with the rest of `agents/runtime/`.
+
+// cache-invalidation: regenerated WHOLESALE from the record files on every run
+// (`writeTargetIndex` recomputes from scratch — no incremental or partial
+// state), and the output is deterministic by construction, so a stale read is
+// impossible and a version namespace would name a format nothing reads across
+// runs. The shape change that would matter is a shape change to the records
+// themselves, which `validateRecord` already gates.
+export const TARGET_INDEX_FILE = '_target-index.json';
+
+export interface TargetCount {
+    target: string;
+    /** Sum of `occurrences` across every record naming this target. */
+    occurrences: number;
+    /** Fingerprints naming it — a per-target count of DISTINCT manifestations. */
+    records: string[];
+}
+
+function targetIndexPath(root: string): string {
+    return path.join(storeDir(root), TARGET_INDEX_FILE);
+}
+
+/** Aggregate occurrences by target. Pure over the store's record files. */
+export function targetCounts(root: string): TargetCount[] {
+    const acc = new Map<string, { occurrences: number; records: string[] }>();
+    for (const rec of listRecords(root)) {
+        for (const value of rec.target ?? []) {
+            const prev = acc.get(value) ?? { occurrences: 0, records: [] };
+            prev.occurrences += Number.isFinite(rec.occurrences) ? rec.occurrences : 0;
+            if (!prev.records.includes(rec.fingerprint)) prev.records.push(rec.fingerprint);
+            acc.set(value, prev);
+        }
+    }
+    return [...acc.entries()]
+        .map(([target, v]) => ({
+            target,
+            occurrences: v.occurrences,
+            records: [...v.records].sort(),
+        }))
+        .sort((a, b) => (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
+}
+
+/**
+ * Write the derived index. Deterministic by construction — sorted keys, sorted
+ * fingerprints, no timestamp — so deleting it and rebuilding produces the same
+ * bytes. A timestamp here would make the artifact look fresh while saying
+ * nothing, and would destroy the one property that makes a rebuild routine.
+ */
+export function writeTargetIndex(root: string): TargetCount[] {
+    const counts = targetCounts(root);
+    fs.mkdirSync(storeDir(root), { recursive: true });
+    fs.writeFileSync(targetIndexPath(root), `${JSON.stringify(counts, null, 2)}\n`, 'utf-8');
+    return counts;
+}
+
+// status transitions
+
+/**
+ * Migrate `released` records — the retired status — to `actioned`, carrying a
+ * resolution line that says the migration is why. Idempotent: a record already
+ * on the new enum is left byte-identical, so running it twice over a store
+ * produces no second diff.
+ *
+ * Returns the fingerprints it changed.
+ */
+export function migrateReleasedRecords(root: string): string[] {
+    const changed: string[] = [];
+    for (const rec of listRecords(root)) {
+        if ((rec.status as string) !== 'released') continue;
+        const next: DefectRecord = {
+            ...rec,
+            status: 'actioned',
+            resolution:
+                rec.resolution ??
+                'migrated from the retired `released` status; the release itself is the action recorded',
+        };
+        writeRecord(root, next);
+        changed.push(rec.fingerprint);
+    }
+    return changed.sort();
+}
+
+/** Move a record to a terminal or parked status, validating the result. */
+export function setStatus(
+    root: string,
+    fp: string,
+    next: DefectRecord['status'],
+    now: string,
+    extra?: { parked_until?: string; resolution?: string },
+): DefectRecord | null {
+    const rec = readRecord(root, fp);
+    if (rec === null) return null;
+    const updated: DefectRecord = {
+        ...rec,
+        status: next,
+        last_seen: now,
+        ...(extra?.parked_until !== undefined ? { parked_until: extra.parked_until } : {}),
+        ...(extra?.resolution !== undefined ? { resolution: extra.resolution } : {}),
+    };
+    if (next !== 'parked') delete updated.parked_until;
+    const problems = validateRecord(updated);
+    if (problems.length > 0) {
+        throw new Error(`refusing to write an invalid record: ${problems.join('; ')}`);
+    }
+    writeRecord(root, updated);
+    return updated;
+}

package/src/scripts/_lib/structured_ask.ts

@@ -0,0 +1,117 @@
+/**
+ * The structured-ask surface — one shared definition of "a host's own question
+ * tool", read by every consumer that needs it.
+ *
+ * Three consumers exist and they must not each invent their own answer:
+ *
+ *   - `probe_unblocked_ask.ts` partitions hand-back ask turns into `text` and
+ *     `native`, where `native` means the turn carried a call to such a tool.
+ *   - `hooks/one_question_per_ask_hook.ts` denies a call carrying more than one
+ *     question.
+ *   - `_lib/host_capability.ts` carries the boolean `structured_ask` capability;
+ *     the per-host SHAPE lives here rather than in the manifest, because every
+ *     manifest field is a strict boolean that `asBool` coerces — a nested object
+ *     put there would normalize silently to `false`.
+ *
+ * What is observed, and what is a shape guess — the line is drawn explicitly.
+ *
+ * `STRUCTURED_ASK_SHAPES` is **empty**. No host in this repository's registry
+ * carries an observed structured-ask tool, so there is no per-host tool name to
+ * match on, and inventing one from a vendor's documentation is exactly what
+ * `host-capability-manifest.md` § Observation protocol forbids.
+ *
+ * `STRUCTURED_ASK_TOOL_NAME_RE` is therefore a **name-shape pattern, not a host
+ * fact**. It exists so that if such a tool ever appears in a transcript, the
+ * probe MEASURES it rather than missing it — and so the number it reports today
+ * (zero) is a measurement rather than an absence of instrumentation. A reader
+ * must not read a match as evidence that a named host ships that tool; the only
+ * thing that establishes that is an observation written into
+ * `STRUCTURED_ASK_SHAPES` with the protocol's four-part citation.
+ *
+ * Consequence, stated rather than discovered later: `native` is expected to be
+ * **0** on every corpus this repo can scan today. That is the honest reading of
+ * a capability nobody has observed, not a broken detector.
+ */
+
+/** The per-host shape of a structured-ask tool, once one has been OBSERVED. */
+export interface StructuredAskShape {
+    /** The tool name as it appears in a transcript's `tool_use` block. */
+    readonly tool: string;
+    /** How many questions one call may carry. `1` is the shape this repo wants. */
+    readonly max_questions: number;
+    /** How many options one question may offer. */
+    readonly max_options_per_question: number;
+    /** Whether the host's picker admits a free-text answer alongside the options. */
+    readonly free_text: boolean;
+}
+
+/**
+ * Observed per-host structured-ask shapes.
+ *
+ * EMPTY, deliberately. A row is written only from an observation in a real
+ * session under `contexts/execution/host-capability-manifest.md` § Observation
+ * protocol — host · host version · transcript reference · date. Never from a
+ * host's documentation, and never by analogy to another host.
+ */
+export const STRUCTURED_ASK_SHAPES: Readonly<Record<string, StructuredAskShape>> = {};
+
+/** The observed shape for `hostId`, or `undefined` when none has been observed. */
+export function structuredAskShape(
+    hostId: string | null | undefined,
+): StructuredAskShape | undefined {
+    if (hostId === null || hostId === undefined) {
+        return undefined;
+    }
+    return STRUCTURED_ASK_SHAPES[hostId];
+}
+
+/**
+ * Name-SHAPE pattern for a structured-ask tool. See the module header: this is
+ * a matcher, not a claim about any host.
+ */
+export const STRUCTURED_ASK_TOOL_NAME_RE = /^(ask[_-]?user[_-]?question|user[_-]?question|ask[_-]?question)s?$/i;
+
+/**
+ * Is `name` a structured-ask tool call?
+ *
+ * An observed per-host shape wins outright — that is a fact about the host. The
+ * name-shape pattern is the fallback, and it is why the probe can report a
+ * measured zero instead of nothing at all.
+ */
+export function isStructuredAskTool(name: string, hostId?: string | null): boolean {
+    const shape = structuredAskShape(hostId);
+    if (shape !== undefined) {
+        return name === shape.tool;
+    }
+    return STRUCTURED_ASK_TOOL_NAME_RE.test(name);
+}
+
+/**
+ * How many questions a structured-ask tool payload carries.
+ *
+ * Returns `-1` when the payload's shape is not recognised at all — a caller
+ * that gates on this must treat `-1` as "cannot tell", never as "one". The two
+ * recognised shapes are the only ones a picker can plausibly use: an array of
+ * question objects under a `questions`-like key, or a single question field.
+ *
+ * A `questions` array of length 0 is 0, not 1: an empty ask is malformed and a
+ * gate should be able to say so.
+ */
+export function countStructuredAskQuestions(input: unknown): number {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        return -1;
+    }
+    const src = input as Record<string, unknown>;
+    for (const key of ['questions', 'question_list', 'items', 'prompts']) {
+        const v = src[key];
+        if (Array.isArray(v)) {
+            return v.length;
+        }
+    }
+    for (const key of ['question', 'prompt', 'header']) {
+        if (typeof src[key] === 'string' && (src[key] as string).trim() !== '') {
+            return 1;
+        }
+    }
+    return -1;
+}

package/src/scripts/_lib/subagent_capsule.ts

@@ -109,7 +109,39 @@ export interface WorkerCapsule {
  * affordable precisely here — an envelope is consume-once and expires in
  * hours, so the migration window is a session, not a release.
  */
-export const CAPSULE_SCHEMA_VERSION = 3;
+export const CAPSULE_SCHEMA_VERSION = 4;
+
+/**
+ * Versions a reader ACCEPTS. Version 4 is the first bump that is purely
+ * ADDITIVE, and that is why it widens the accepted set instead of replacing it.
+ *
+ * The compatibility contract is stated here rather than inferred.
+ *
+ * - **Scope.** The version is ENVELOPE-WIDE, not per-variant. One number
+ *   describes the whole schema module, so a variant added later does not
+ *   silently re-date records of another variant.
+ * - **New reader, old record.** A v3 record validates. Its required set is v3's
+ *   — the fields added at v4 are not demanded of it, because demanding them
+ *   would be a retroactive requirement on records already written.
+ * - **Old reader, new record.** A v3-only reader rejects a v4 record with the
+ *   version violation named. That is the pre-existing loud-discard behaviour and
+ *   is affordable for the same reason v3 gave: a record is consume-once and
+ *   expires in {@link RECYCLE_MAX_AGE_HOURS} hours, so the migration window is a
+ *   session, not a release.
+ * - **Unknown version.** Anything outside this set is rejected with the set
+ *   printed. Absent is not a pass — an undated record is not "probably current".
+ * - **Unknown variant.** Rejected by `variant` check, never coerced. A reader
+ *   that does not know a variant must not guess at its required fields.
+ * - **Rollback.** Reverting to a v3-only reader after v4 records exist discards
+ *   those records loudly rather than mis-reading them; the loss is one session's
+ *   resume, which is the same loss as no record at all.
+ *
+ * Adding a required field is what forced v3 to be a hard break. v4 adds
+ * `successful_approaches`, `open_questions` and `predecessor`, and requires the
+ * first and third **only of records that declare themselves v4** — so no
+ * previously valid record becomes invalid.
+ */
+export const ACCEPTED_CAPSULE_VERSIONS: readonly number[] = [3, 4];
 
 /** The two CHECKPOINT variants sharing this schema. */
 export const CAPSULE_VARIANTS = ['worker', 'main_session'] as const;
@@ -280,6 +312,30 @@ export function validateCapsule(input: unknown): string[] {
  * wire gate; this variant is consumed from a FILE by
  * `handoff_context_hook`, so the module itself must be the strict gate.
  */
+/**
+ * The four questions a resuming session asks, and the field that answers each —
+ * written down rather than left implicit, because the gap that produced
+ * `successful_approaches` stayed invisible for exactly as long as the mapping
+ * was unwritten: three of the four had a field, the fourth had nothing, and no
+ * reader of the schema had a reason to notice.
+ *
+ * *What was it about?* is answered directly by `task`, with `summary` carrying
+ * the one-line outcome. *What was the goal?* is answered only by PROXY:
+ * `acceptance_criteria` states what **done** means, which is the goal expressed
+ * as a test rather than as an intention, and `next_task` narrows it to the
+ * successor's first move. *What did NOT work?* is `failed_approaches`, direct,
+ * required, explicit `none`. *What DID work?* is `successful_approaches`,
+ * direct, required at version 4, explicit `none`.
+ *
+ * The one proxy is labelled a proxy on purpose. A goal can be met by criteria
+ * nobody wrote down, so reading `acceptance_criteria` as the goal itself is the
+ * error the label exists to prevent.
+ *
+ * Everything else the schema carries — `remaining`, `not_carried_forward`,
+ * `constraints`, `decisions`, `open_questions`, the drift anchor — answers a
+ * question the four do not ask. That is not surplus; it is simply outside this
+ * mapping.
+ */
 export interface MainSessionRecycleEnvelope {
     /** Must be {@link CAPSULE_SCHEMA_VERSION}. */
     capsule_version: number;
@@ -371,6 +427,59 @@ export interface MainSessionRecycleEnvelope {
      * successor re-burning a recorded dead end.
      */
     failed_approaches: string[];
+    /**
+     * Approaches this session tried and KEPT — "did X, it worked because Y".
+     *
+     * **The counterpart `failed_approaches` did not have**, and its absence was
+     * a structural defect rather than an omission: a record that can say what to
+     * avoid and cannot say what to repeat is pessimistic by construction, and a
+     * successor re-derives every working decision from scratch while being
+     * warned off the dead ends.
+     *
+     * Required at capsule version 4 with at least one entry, for exactly the
+     * reason `failed_approaches` is: a session that kept nothing writes the
+     * single entry `none` explicitly, so "nothing worked" stays distinguishable
+     * from "nobody wrote it down". An optional field would re-create the silence
+     * one layer down.
+     */
+    successful_approaches?: string[];
+    /**
+     * Questions this session could not settle — the successor's first reading
+     * list. The worker variant has carried `open_risks` since v1
+     * (`WorkerCapsule.open_risks`) and the handoff template asks for open
+     * questions in prose; the session variant had neither, so the one thing a
+     * resuming session most needs to not silently drop had no field.
+     *
+     * Optional, unlike `successful_approaches`: an empty question list is not
+     * the same asymmetry — a record with nothing open is a complete claim, and
+     * `remaining` already carries the work.
+     */
+    open_questions?: string[];
+    /**
+     * The session that WROTE this record.
+     *
+     * Added with `predecessor` and not separable from it: an edge needs two
+     * endpoints, and before v4 a record carried neither. `workspace` answers
+     * "which checkout", which is what the identity check needs; it cannot
+     * answer "which session", which is what a chain needs.
+     */
+    session_id?: string;
+    /**
+     * The session this one continues, or the explicit string `none`.
+     *
+     * Required at capsule version 4. Before it, `grep -rn
+     * "predecessor_session\|lineage_id" src/` returned 0 and the reader
+     * injected whatever record was lying at the path — which is not the same
+     * question as "which record is mine" that the session key answers. A key
+     * says whose record this is; a predecessor edge says which record this
+     * session should be reading.
+     *
+     * `none` is a STATED ABSENCE, never an empty string or a missing field. The
+     * first session in a workspace has no predecessor and says so, so a reader
+     * never waits on something that will not arrive — and a NAMED predecessor
+     * that is absent is a refusal, never a fall-through to a different record.
+     */
+    predecessor?: string;
     /**
      * Drift anchor — all three, or none of them is one. Identity is the
      * canonicalized remote (or the realpath of the common git dir when there
@@ -615,6 +724,10 @@ const RECYCLE_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
     'next_task',
     'suggested_skills',
     'failed_approaches',
+    'successful_approaches',
+    'open_questions',
+    'predecessor',
+    'session_id',
     'repo_identity',
     'branch',
     'head',
@@ -644,9 +757,16 @@ export function validateRecycleEnvelope(input: unknown): string[] {
         }
     }
 
-    if (e['capsule_version'] !== CAPSULE_SCHEMA_VERSION) {
-        errors.push(`capsule_version must be ${CAPSULE_SCHEMA_VERSION}`);
+    const version = e['capsule_version'];
+    if (typeof version !== 'number' || !ACCEPTED_CAPSULE_VERSIONS.includes(version)) {
+        errors.push(`capsule_version must be one of ${ACCEPTED_CAPSULE_VERSIONS.join(' | ')}`);
     }
+    // Requiredness is version-conditional, and only in the additive direction:
+    // a v4 record owes the v4 fields, a v3 record owes exactly what v3 owed.
+    // Demanding the new fields of an already-written record would be a
+    // retroactive requirement, which is the one thing the recorded schema lock
+    // forbids ("add fields or variants, never repurpose or remove one").
+    const atV4 = version === 4;
     if (e['variant'] !== 'main_session') {
         errors.push("variant must be 'main_session'");
     }
@@ -697,6 +817,38 @@ export function validateRecycleEnvelope(input: unknown): string[] {
         );
     }
 
+    // Version 4 additions. `successful_approaches` mirrors `failed_approaches`
+    // exactly — required with >= 1 entry, `none` written explicitly — because
+    // the asymmetry between the two is the defect the field exists to remove,
+    // and an optional counterpart to a required field re-creates it.
+    checkList(errors, 'successful_approaches', e['successful_approaches'], MAX_LINE_CHARS, atV4);
+    if (Array.isArray(e['successful_approaches']) && e['successful_approaches'].length === 0) {
+        errors.push(
+            'successful_approaches must carry at least one entry — write "none" explicitly, so ' +
+                'silence and "nothing worked" stay distinguishable',
+        );
+    }
+    checkList(errors, 'open_questions', e['open_questions'], MAX_LINE_CHARS, false);
+
+    // The predecessor edge (Phase 2.3). Required at v4, and an EMPTY value is
+    // not an answer: `none` is a claim ("this session starts a chain"), absence
+    // is a reader waiting for something that will not arrive.
+    const predecessor = e['predecessor'];
+    if (predecessor === undefined) {
+        if (atV4) {
+            errors.push(
+                'predecessor is required — name the session this one continues, or write "none" ' +
+                    'explicitly for the first session in a workspace',
+            );
+        }
+    } else if (!isShortLine(predecessor, MAX_REF_CHARS)) {
+        errors.push(`predecessor must be a single line of 1–${MAX_REF_CHARS} chars ("none" when there is no predecessor)`);
+    }
+
+    if (e['session_id'] !== undefined && !isShortLine(e['session_id'], MAX_REF_CHARS)) {
+        errors.push(`session_id must be a single line of 1–${MAX_REF_CHARS} chars`);
+    }
+
     // Drift anchor (Phase 3.2). Optional as a set — an older envelope simply
     // has none — but each present field must still be a short line.
     for (const field of ['repo_identity', 'branch', 'head', 'status_summary', 'last_verify'] as const) {