@cleocode/core 2026.9.24 → 2026.9.26

package/dist/memory/manifest-identity.js

@@ -0,0 +1,345 @@
+/**
+ * Manifest identity validation — the entry id, the linked task ids and the
+ * file reference of a `pipeline_manifest` entry (T12829).
+ *
+ * Before this module `cleo manifest append` stored whatever it was given: a
+ * `--task` of `T99999` (no such task), a 900-character JSON blob, or
+ * `../../x`. The shorthand builder turns `--task` into both the entry id and
+ * the `file` reference (`.cleo/agent-outputs/<task>-<type>-<stamp>.md`), and
+ * `cleo manifest show` reads `file` relative to the project root. So the blob
+ * became an unreadable path (ENAMETOOLONG), and a `../` task made `show` read
+ * a file outside the project. Nothing is written to that path; the defect is
+ * an unvalidated identity that later flows into a filesystem read.
+ *
+ * Every check here is pure except {@link findMissingLinkedTasks}, which reads
+ * the task store. Append rejects a problem before writing; show refuses a
+ * malformed id or unsafe file before touching the filesystem; `cleo doctor
+ * manifest-rows` reports rows stored before these checks existed.
+ *
+ * @module
+ * @task T12829
+ */
+import { closeSync, constants as fsConstants, fstatSync, openSync, readFileSync, realpathSync, statSync, } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { isStorableTaskId, isTaskId } from '@cleocode/contracts';
+/** Longest accepted manifest entry id. */
+export const MANIFEST_ENTRY_ID_MAX_LENGTH = 200;
+/**
+ * Accepted manifest entry id characters: an alphanumeric first character,
+ * then alphanumerics and `.`, `_`, `:`, `@`, `+`, `-`. No path separator,
+ * whitespace or control character can appear, so an id can never name a
+ * path outside the directory it is joined onto.
+ */
+export const MANIFEST_ENTRY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@+-]*$/;
+/** Longest accepted `file` reference. */
+export const MANIFEST_FILE_MAX_LENGTH = 1024;
+/** Longest accepted single path segment of a `file` reference (filesystem NAME_MAX). */
+export const MANIFEST_FILE_SEGMENT_MAX_BYTES = 255;
+/** A URI-shaped `file` reference (`cleo://docs/...`); `show` validates these itself. */
+const URI_REFERENCE = /^[a-z][a-z\d+.-]*:/i;
+/** A Windows drive path (`C:\x`, `C:/x`, drive-relative `C:x`), which is a path and not a URI. */
+const WINDOWS_DRIVE = /^[a-z]:/i;
+/** A UNC-looking reference (`\\server\share`, `//server/share`). */
+const UNC_REFERENCE = /^[\\/]{2}/;
+/** Control characters, which no id or path reference may contain. */
+const CONTROL_CHARS = /[\x00-\x1f\x7f]/;
+/**
+ * Structured task ids CLEO mints on purpose alongside the canonical `T<digits>`
+ * (`T-RECONCILE-FOLLOWUP-v2026.5.63-6`, see `isStorableTaskId`): a `T`, then
+ * letters, digits, `.`, `_` and `-` only.
+ */
+const STRUCTURED_TASK_ID = /^T[A-Za-z0-9._-]+$/;
+/**
+ * Whether `value` is acceptable as a manifest linked task id: the canonical
+ * `T<digits>` shape, or a structured `T…` id CLEO mints and stores
+ * (`isStorableTaskId`, at most 64 characters, no whitespace or separators).
+ * A JSON blob, a path, or an over-long value is never accepted.
+ *
+ * @param value - Candidate task id.
+ * @returns `true` when the value can name a task.
+ */
+export function isManifestTaskId(value) {
+    if (isTaskId(value))
+        return true;
+    return typeof value === 'string' && isStorableTaskId(value) && STRUCTURED_TASK_ID.test(value);
+}
+/**
+ * Truncate a value for display in an issue so a huge input cannot flood output.
+ *
+ * @param value - Raw value.
+ * @returns At most 120 characters, with an ellipsis and the full length when cut.
+ */
+function preview(value) {
+    return value.length <= 120 ? value : `${value.slice(0, 120)}… (${value.length} chars)`;
+}
+/**
+ * Why a manifest entry id is unacceptable, or `null` when it is fine.
+ *
+ * @param id - Candidate entry id.
+ * @returns A reason, or `null`.
+ * @example
+ * ```ts
+ * manifestEntryIdProblem('T123-implementation-20260929'); // null
+ * manifestEntryIdProblem('../../x');                      // 'must start with ...'
+ * ```
+ */
+export function manifestEntryIdProblem(id) {
+    if (typeof id !== 'string' || id === '')
+        return 'id must be a non-empty string';
+    if (id.length > MANIFEST_ENTRY_ID_MAX_LENGTH) {
+        return `id is ${id.length} characters; the maximum is ${MANIFEST_ENTRY_ID_MAX_LENGTH}`;
+    }
+    if (!MANIFEST_ENTRY_ID_PATTERN.test(id)) {
+        return 'id must start with a letter or digit and contain only letters, digits and . _ : @ + -';
+    }
+    return null;
+}
+/**
+ * Why a manifest `file` reference is unsafe, or `null` when it is fine.
+ *
+ * Lexical checks only: an absolute, drive, UNC or backslash path is refused,
+ * and the reference joined onto `root` must stay inside `root`. A symbolic
+ * link inside the project can still point outside it, so every reader goes
+ * through {@link resolveContainedFile} / {@link readContainedFile}, which
+ * resolve real paths. URI references are left to `show`, which accepts only
+ * `cleo://docs/<reference>`.
+ *
+ * @param file - Candidate `file` value.
+ * @param root - Directory the reference is resolved against.
+ * @returns A reason, or `null`.
+ */
+export function manifestFileProblem(file, root) {
+    if (typeof file !== 'string' || file === '')
+        return 'file must be a non-empty string';
+    if (file.length > MANIFEST_FILE_MAX_LENGTH) {
+        return `file is ${file.length} characters; the maximum is ${MANIFEST_FILE_MAX_LENGTH}`;
+    }
+    if (CONTROL_CHARS.test(file))
+        return 'file must not contain control characters';
+    if (UNC_REFERENCE.test(file))
+        return 'file must not be a UNC path';
+    if (file.includes('\\'))
+        return 'file must not contain a backslash';
+    if (WINDOWS_DRIVE.test(file))
+        return 'file must not be a Windows drive path';
+    if (file.startsWith('/') || isAbsolute(file))
+        return 'file must be a relative path';
+    if (URI_REFERENCE.test(file))
+        return null;
+    const tooLong = file
+        .split(/[\\/]/)
+        .find((segment) => Buffer.byteLength(segment, 'utf8') > MANIFEST_FILE_SEGMENT_MAX_BYTES);
+    if (tooLong !== undefined) {
+        return `file has a path segment longer than ${MANIFEST_FILE_SEGMENT_MAX_BYTES} bytes`;
+    }
+    const rel = relative(root, join(root, file));
+    if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        return 'file must resolve to a path inside the project';
+    }
+    return null;
+}
+/**
+ * Format checks for a manifest entry's id, linked task ids and file reference
+ * (an absent `file` is not checked). Pure: no store access. Pair with {@link findMissingLinkedTasks} to check
+ * that the linked tasks exist.
+ *
+ * @param entry - The entry's identity fields.
+ * @param root - Directory `file` is resolved against (the project root).
+ * @returns Every problem found; empty when the entry is well formed.
+ */
+export function manifestIdentityIssues(entry, root) {
+    const issues = [];
+    const idProblem = manifestEntryIdProblem(entry.id);
+    if (idProblem) {
+        issues.push({
+            field: 'id',
+            code: 'E_VALIDATION',
+            value: preview(String(entry.id ?? '')),
+            message: idProblem,
+        });
+    }
+    if (entry.linked_tasks !== undefined) {
+        if (!Array.isArray(entry.linked_tasks)) {
+            issues.push({
+                field: 'linked_tasks',
+                code: 'E_VALIDATION',
+                value: preview(String(entry.linked_tasks)),
+                message: 'linked_tasks must be an array of task ids',
+            });
+        }
+        else {
+            for (const taskId of entry.linked_tasks) {
+                if (!isManifestTaskId(taskId)) {
+                    issues.push({
+                        field: 'linked_tasks',
+                        code: 'E_VALIDATION',
+                        value: preview(String(taskId)),
+                        message: 'linked task id must be a task id such as T1234',
+                    });
+                }
+            }
+        }
+    }
+    // An absent file is the caller's required-field check; only a present one is resolved.
+    const fileProblem = entry.file === undefined ? null : manifestFileProblem(entry.file, root);
+    if (fileProblem) {
+        issues.push({
+            field: 'file',
+            code: 'E_VALIDATION',
+            value: preview(String(entry.file ?? '')),
+            message: fileProblem,
+        });
+    }
+    return issues;
+}
+/**
+ * The well-formed linked task ids that name no task in the project store
+ * (archived tasks count as existing).
+ *
+ * @param taskIds - Linked task ids; malformed ones are skipped (format checks report them).
+ * @param projectRoot - Project whose task store is consulted.
+ * @returns The ids with no task, in input order, without duplicates.
+ */
+export async function findMissingLinkedTasks(taskIds, projectRoot) {
+    const wellFormed = [...new Set(taskIds.filter((id) => isManifestTaskId(id)))];
+    if (wellFormed.length === 0)
+        return [];
+    const { getTaskAccessor } = await import('../store/data-accessor.js');
+    const accessor = await getTaskAccessor(projectRoot);
+    const missing = [];
+    for (const id of wellFormed) {
+        if (!(await accessor.taskExists(id)))
+            missing.push(id);
+    }
+    return missing;
+}
+/**
+ * The error code carried by a thrown filesystem error, when it has one.
+ *
+ * @param error - Caught value.
+ * @returns The `code` string, or `undefined`.
+ */
+function errnoCode(error) {
+    return error instanceof Error && 'code' in error && typeof error.code === 'string'
+        ? error.code
+        : undefined;
+}
+/** Filesystem errors that mean "nothing is there" for a manifest reference. */
+const NOT_FOUND_CODES = new Set(['ENOENT', 'ENOTDIR']);
+/**
+ * Whether `realTarget` lies strictly inside `realRoot` (separator-safe: a
+ * sibling `/proj-evil` is not inside `/proj`).
+ *
+ * @param realRoot - Real (symlink-free) root directory.
+ * @param realTarget - Real (symlink-free) candidate path.
+ * @returns `true` when the target is a descendant of the root.
+ */
+function isInsideRealRoot(realRoot, realTarget) {
+    const prefix = realRoot.endsWith(sep) ? realRoot : `${realRoot}${sep}`;
+    return realTarget.startsWith(prefix);
+}
+/**
+ * Resolve a manifest `file` reference to its real path, requiring it to stay
+ * inside `root` after every symbolic link is followed (T12829).
+ *
+ * {@link manifestFileProblem} is lexical: `link/secret.txt` passes when
+ * `link` is an in-project symlink to a directory outside the project. This
+ * resolves both the root and the target with `realpathSync` and requires the
+ * real target under the real root. A missing target (or a dangling link) is
+ * `not-found` and must not be read; a URI reference is `unsafe` here because
+ * it is not a filesystem path.
+ *
+ * @param root - Directory the reference is resolved against.
+ * @param file - The stored `file` reference.
+ * @returns The resolution; only `ok` may be read, and only via `realPath`.
+ * @throws The underlying filesystem error for anything other than not-found or a link loop.
+ * @example
+ * ```ts
+ * resolveContainedFile('/proj', 'link/secret.txt'); // { status: 'unsafe', ... } when link -> ../outside
+ * ```
+ */
+export function resolveContainedFile(root, file) {
+    const problem = manifestFileProblem(file, root);
+    if (problem)
+        return { status: 'unsafe', reason: problem };
+    if (typeof file !== 'string' || URI_REFERENCE.test(file)) {
+        return { status: 'unsafe', reason: 'file must be a filesystem path, not a URI' };
+    }
+    let realRoot;
+    let realTarget;
+    try {
+        realRoot = realpathSync(root);
+        realTarget = realpathSync(join(realRoot, file));
+    }
+    catch (error) {
+        const code = errnoCode(error);
+        if (code !== undefined && NOT_FOUND_CODES.has(code))
+            return { status: 'not-found' };
+        if (code === 'ELOOP')
+            return { status: 'unsafe', reason: 'file is a symbolic link loop' };
+        throw error;
+    }
+    if (!isInsideRealRoot(realRoot, realTarget)) {
+        return {
+            status: 'unsafe',
+            reason: 'file resolves (through a symbolic link) outside the project',
+        };
+    }
+    return { status: 'ok', realPath: realTarget };
+}
+/**
+ * Read a manifest `file` reference as UTF-8 text, only when its real path is
+ * inside `root` (see {@link resolveContainedFile}).
+ *
+ * The resolved real path is opened once, without following a final symbolic
+ * link and without blocking on a FIFO, and the content is read through that
+ * file descriptor. After opening, the path is re-resolved and must still name
+ * the same inode, so a component swapped for a link between the check and the
+ * open is refused rather than read.
+ *
+ * @param root - Directory the reference is resolved against.
+ * @param file - The stored `file` reference.
+ * @returns The content, or why it was not read.
+ * @throws The underlying filesystem error for failures other than not-found
+ *   (a directory throws `EISDIR`).
+ */
+export function readContainedFile(root, file) {
+    const resolved = resolveContainedFile(root, file);
+    if (resolved.status !== 'ok')
+        return resolved;
+    const flags = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0);
+    let fd;
+    try {
+        fd = openSync(resolved.realPath, flags);
+    }
+    catch (error) {
+        const code = errnoCode(error);
+        if (code !== undefined && NOT_FOUND_CODES.has(code))
+            return { status: 'not-found' };
+        if (code === 'ELOOP') {
+            return { status: 'unsafe', reason: 'file changed into a symbolic link while being read' };
+        }
+        throw error;
+    }
+    try {
+        const opened = fstatSync(fd);
+        // A directory falls through to the read, which fails with EISDIR like any
+        // other read failure; a FIFO, socket or device is never read.
+        if (!opened.isFile() && !opened.isDirectory()) {
+            return { status: 'unsafe', reason: 'file is not a regular file' };
+        }
+        const again = resolveContainedFile(root, file);
+        if (again.status !== 'ok' || again.realPath !== resolved.realPath) {
+            return { status: 'unsafe', reason: 'file changed while being read' };
+        }
+        const current = statSync(again.realPath);
+        if (current.dev !== opened.dev || current.ino !== opened.ino) {
+            return { status: 'unsafe', reason: 'file changed while being read' };
+        }
+        return { status: 'ok', realPath: resolved.realPath, content: readFileSync(fd, 'utf-8') };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+//# sourceMappingURL=manifest-identity.js.map

package/dist/memory/manifest-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-identity.js","sourceRoot":"","sources":["../../src/memory/manifest-identity.ts"],"names":[],"mappings":"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"}

package/dist/memory/mental-model-queue.d.ts

@@ -7,10 +7,20 @@
  * decouples the hot path (agent execution) from I/O latency.
  *
  * The queue is drained to brain.db either:
- *   1. Periodically — every {@link FLUSH_INTERVAL_MS} milliseconds via a timer.
- *   2. On high watermark — when the queue exceeds {@link FLUSH_WATERMARK} entries.
- *   3. On process exit — SIGINT, SIGTERM, and 'exit' hooks perform a best-effort
- *      synchronous flush so no observations are lost.
+ *   1. Promptly — every `enqueue` schedules a drain on the next macrotask
+ *      (`setImmediate`, NOT unref'd), so observations enqueued in the same tick
+ *      are written as one batch and the caller's promise always settles (T12817).
+ *   2. Periodically — every {@link FLUSH_INTERVAL_MS} milliseconds via a timer
+ *      (backstop; unref'd).
+ *   3. On high watermark — when the queue exceeds {@link FLUSH_WATERMARK} entries.
+ *   4. On process exit — SIGINT, SIGTERM, and 'exit' hooks perform a best-effort
+ *      flush.
+ *
+ * T12817: before the prompt drain existed, the ONLY drain a one-shot process
+ * could reach was the unref'd 5 s timer. `enqueue()` returned a promise that
+ * only that timer could settle, so an awaited `cleo memory observe --agent X`
+ * left the event loop empty: Node exited 0 with zero bytes on stdout and the
+ * `'exit'` hook's async drain never ran — the observation was silently lost.
  *
  * Observations without an `agent` field continue to use the existing synchronous
  * path in observeBrain() and are never routed here.

package/dist/memory/mental-model-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mental-model-queue.d.ts","sourceRoot":"","sources":["../../src/memory/mental-model-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AA4BnF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAC7C,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;;;;;OAOG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzB,2DAA2D;IAC3D,IAAI,IAAI,MAAM,CAAC;CAChB;AAiJD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,gBAyC9B,CAAC;AAMF;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAgBrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAI5E"}
+{"version":3,"file":"mental-model-queue.d.ts","sourceRoot":"","sources":["../../src/memory/mental-model-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AA4BnF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAC7C,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;;;;;OAOG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzB,2DAA2D;IAC3D,IAAI,IAAI,MAAM,CAAC;CAChB;AA8KD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,gBA8B9B,CAAC;AAMF;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAoBrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAI5E"}

package/dist/memory/mental-model-queue.js

@@ -7,10 +7,20 @@
  * decouples the hot path (agent execution) from I/O latency.
  *
  * The queue is drained to brain.db either:
- *   1. Periodically — every {@link FLUSH_INTERVAL_MS} milliseconds via a timer.
- *   2. On high watermark — when the queue exceeds {@link FLUSH_WATERMARK} entries.
- *   3. On process exit — SIGINT, SIGTERM, and 'exit' hooks perform a best-effort
- *      synchronous flush so no observations are lost.
+ *   1. Promptly — every `enqueue` schedules a drain on the next macrotask
+ *      (`setImmediate`, NOT unref'd), so observations enqueued in the same tick
+ *      are written as one batch and the caller's promise always settles (T12817).
+ *   2. Periodically — every {@link FLUSH_INTERVAL_MS} milliseconds via a timer
+ *      (backstop; unref'd).
+ *   3. On high watermark — when the queue exceeds {@link FLUSH_WATERMARK} entries.
+ *   4. On process exit — SIGINT, SIGTERM, and 'exit' hooks perform a best-effort
+ *      flush.
+ *
+ * T12817: before the prompt drain existed, the ONLY drain a one-shot process
+ * could reach was the unref'd 5 s timer. `enqueue()` returned a promise that
+ * only that timer could settle, so an awaited `cleo memory observe --agent X`
+ * left the event loop empty: Node exited 0 with zero bytes on stdout and the
+ * `'exit'` hook's async drain never ran — the observation was silently lost.
  *
  * Observations without an `agent` field continue to use the existing synchronous
  * path in observeBrain() and are never routed here.
@@ -45,12 +55,18 @@ const MENTAL_MODEL_TYPES = new Set([
 // ---------------------------------------------------------------------------
 /** In-memory queue of pending mental-model observations. */
 const _queue = [];
-/** Whether a flush is currently in progress (prevents re-entrant flushes). */
-let _flushing = false;
 /** Whether process-exit hooks have been registered. */
 let _hooksRegistered = false;
 /** Handle for the periodic flush timer (undefined = no active timer). */
 let _timer;
+/** Handle for the pending prompt drain (undefined = none scheduled). T12817 */
+let _immediate;
+/**
+ * Tail of the serialized drain chain. Every drain runs after the previous one
+ * settles, so entries enqueued while a drain is in flight are picked up by the
+ * next link instead of waiting for the unref'd timer. T12817
+ */
+let _drainTail = Promise.resolve();
 /**
  * Drain the queue synchronously where possible, or fall back to async writes.
  * Returns when all observations in the current batch have been persisted.
@@ -76,6 +92,33 @@ async function drainQueue() {
     }
     return count;
 }
+/**
+ * Run {@link drainQueue} after every earlier drain has settled.
+ *
+ * @returns The number of observations this drain persisted.
+ */
+function serialDrain() {
+    const next = _drainTail.then(() => drainQueue());
+    _drainTail = next.catch(() => undefined);
+    return next;
+}
+/**
+ * Schedule a prompt drain on the next macrotask (T12817).
+ *
+ * The handle is deliberately NOT unref'd: an enqueued observation is pending
+ * I/O the process owes its caller, so it must keep the event loop alive until
+ * written. Entries enqueued in the same tick share one drain.
+ */
+function schedulePromptDrain() {
+    if (_immediate !== undefined)
+        return;
+    _immediate = setImmediate(() => {
+        _immediate = undefined;
+        serialDrain().catch(() => {
+            /* per-entry errors already rejected their callers */
+        });
+    });
+}
 /**
  * Best-effort synchronous exit flush.
  * Used in 'exit' event handler where async I/O is not guaranteed.
@@ -137,15 +180,8 @@ function ensureTimer() {
     _timer = setInterval(() => {
         if (_queue.length === 0)
             return;
-        if (_flushing)
-            return;
-        _flushing = true;
-        drainQueue()
-            .catch(() => {
+        serialDrain().catch(() => {
             /* best-effort */
-        })
-            .finally(() => {
-            _flushing = false;
         });
     }, FLUSH_INTERVAL_MS);
     // Unref so the timer doesn't prevent process exit when queue is idle
@@ -168,31 +204,20 @@ export const mentalModelQueue = {
         ensureTimer();
         return new Promise((resolve, reject) => {
             _queue.push({ projectRoot, params, resolve, reject });
-            // High-watermark flush
-            if (_queue.length >= FLUSH_WATERMARK && !_flushing) {
-                _flushing = true;
-                drainQueue()
-                    .catch(() => {
+            if (_queue.length >= FLUSH_WATERMARK) {
+                // High-watermark flush
+                serialDrain().catch(() => {
                     /* best-effort */
-                })
-                    .finally(() => {
-                    _flushing = false;
                 });
             }
+            else {
+                // T12817: guarantee the caller's promise settles in a one-shot process.
+                schedulePromptDrain();
+            }
         });
     },
-    async flush() {
-        if (_flushing) {
-            // Wait for the current flush to settle then flush again
-            await new Promise((r) => setTimeout(r, 50));
-        }
-        _flushing = true;
-        try {
-            return await drainQueue();
-        }
-        finally {
-            _flushing = false;
-        }
+    flush() {
+        return serialDrain();
     },
     size() {
         return _queue.length;
@@ -216,13 +241,17 @@ export function _resetMentalModelQueueForTests() {
         clearInterval(_timer);
         _timer = undefined;
     }
+    if (_immediate !== undefined) {
+        clearImmediate(_immediate);
+        _immediate = undefined;
+    }
+    _drainTail = Promise.resolve();
     // Reject all pending observations so test assertions can proceed.
     const pending = _queue.splice(0, _queue.length);
     const cancelErr = new Error('[test teardown] mental-model queue reset');
     for (const entry of pending) {
         entry.reject(cancelErr);
     }
-    _flushing = false;
     _hooksRegistered = false;
 }
 /**

package/dist/memory/mental-model-queue.js.map

@@ -1 +1 @@
-{"version":3,"file":"mental-model-queue.js","sourceRoot":"","sources":["../../src/memory/mental-model-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,sCAAsC;AACtC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC,uEAAuE;AACvE,MAAM,eAAe,GAAG,EAAE,CAAC;AA0D3B,8EAA8E;AAC9E,+DAA+D;AAC/D,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAS;IACzC,WAAW;IACX,QAAQ;IACR,SAAS;IACT,UAAU;IACV,QAAQ;IACR,UAAU;CACX,CAAC,CAAC;AAEH,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E,4DAA4D;AAC5D,MAAM,MAAM,GAAwB,EAAE,CAAC;AAEvC,8EAA8E;AAC9E,IAAI,SAAS,GAAG,KAAK,CAAC;AAEtB,uDAAuD;AACvD,IAAI,gBAAgB,GAAG,KAAK,CAAC;AAE7B,yEAAyE;AACzE,IAAI,MAAkD,CAAC;AAEvD;;;GAGG;AACH,KAAK,UAAU,UAAU;IACvB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAElC,6CAA6C;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,2EAA2E;IAC3E,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAE9D,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;YACnE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACtB,KAAK,EAAE,CAAC;QACV,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAClE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,SAAS;IAChB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAChC,qEAAqE;IACrE,oEAAoE;IACpE,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;QACtB,mDAAmD;IACrD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB;IACxB,IAAI,gBAAgB;QAAE,OAAO;IAC7B,gBAAgB,GAAG,IAAI,CAAC;IAExB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAE9B,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE;QAC1B,6EAA6E;QAC7E,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5D,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,UAAU,EAAE;aACT,KAAK,CAAC,GAAG,EAAE;YACV,iBAAiB;QACnB,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe;QACpC,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;QAC3B,6EAA6E;QAC7E,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5D,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,UAAU,EAAE;aACT,KAAK,CAAC,GAAG,EAAE;YACV,iBAAiB;QACnB,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB;QACrC,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAS,WAAW;IAClB,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO;IACjC,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE;QACxB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAChC,IAAI,SAAS;YAAE,OAAO;QACtB,SAAS,GAAG,IAAI,CAAC;QACjB,UAAU,EAAE;aACT,KAAK,CAAC,GAAG,EAAE;YACV,iBAAiB;QACnB,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC,CAAC,CAAC;IACP,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACtB,qEAAqE;IACrE,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QACvC,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAqB;IAChD,OAAO,CACL,WAAmB,EACnB,MAA8C;QAE9C,iBAAiB,EAAE,CAAC;QACpB,WAAW,EAAE,CAAC;QAEd,OAAO,IAAI,OAAO,CAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACzD,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAEtD,uBAAuB;YACvB,IAAI,MAAM,CAAC,MAAM,IAAI,eAAe,IAAI,CAAC,SAAS,EAAE,CAAC;gBACnD,SAAS,GAAG,IAAI,CAAC;gBACjB,UAAU,EAAE;qBACT,KAAK,CAAC,GAAG,EAAE;oBACV,iBAAiB;gBACnB,CAAC,CAAC;qBACD,OAAO,CAAC,GAAG,EAAE;oBACZ,SAAS,GAAG,KAAK,CAAC;gBACpB,CAAC,CAAC,CAAC;YACP,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,SAAS,EAAE,CAAC;YACd,wDAAwD;YACxD,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACpD,CAAC;QACD,SAAS,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC;YACH,OAAO,MAAM,UAAU,EAAE,CAAC;QAC5B,CAAC;gBAAS,CAAC;YACT,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI;QACF,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;CACF,CAAC;AAEF,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,8BAA8B;IAC5C,iCAAiC;IACjC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,aAAa,CAAC,MAAM,CAAC,CAAC;QACtB,MAAM,GAAG,SAAS,CAAC;IACrB,CAAC;IAED,kEAAkE;IAClE,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IACxE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC1B,CAAC;IAED,SAAS,GAAG,KAAK,CAAC;IAClB,gBAAgB,GAAG,KAAK,CAAC;AAC3B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAA0B;IACjE,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAChC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,WAAW,CAAC;IACxC,OAAO,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"mental-model-queue.js","sourceRoot":"","sources":["../../src/memory/mental-model-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,sCAAsC;AACtC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC,uEAAuE;AACvE,MAAM,eAAe,GAAG,EAAE,CAAC;AA0D3B,8EAA8E;AAC9E,+DAA+D;AAC/D,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAS;IACzC,WAAW;IACX,QAAQ;IACR,SAAS;IACT,UAAU;IACV,QAAQ;IACR,UAAU;CACX,CAAC,CAAC;AAEH,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E,4DAA4D;AAC5D,MAAM,MAAM,GAAwB,EAAE,CAAC;AAEvC,uDAAuD;AACvD,IAAI,gBAAgB,GAAG,KAAK,CAAC;AAE7B,yEAAyE;AACzE,IAAI,MAAkD,CAAC;AAEvD,+EAA+E;AAC/E,IAAI,UAAuD,CAAC;AAE5D;;;;GAIG;AACH,IAAI,UAAU,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;AAErD;;;GAGG;AACH,KAAK,UAAU,UAAU;IACvB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAElC,6CAA6C;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,2EAA2E;IAC3E,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAE9D,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;YACnE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACtB,KAAK,EAAE,CAAC;QACV,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAClE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW;IAClB,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC;IACjD,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACzC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,SAAS,mBAAmB;IAC1B,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO;IACrC,UAAU,GAAG,YAAY,CAAC,GAAG,EAAE;QAC7B,UAAU,GAAG,SAAS,CAAC;QACvB,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;YACvB,qDAAqD;QACvD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,SAAS;IAChB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAChC,qEAAqE;IACrE,oEAAoE;IACpE,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;QACtB,mDAAmD;IACrD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB;IACxB,IAAI,gBAAgB;QAAE,OAAO;IAC7B,gBAAgB,GAAG,IAAI,CAAC;IAExB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAE9B,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE;QAC1B,6EAA6E;QAC7E,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5D,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,UAAU,EAAE;aACT,KAAK,CAAC,GAAG,EAAE;YACV,iBAAiB;QACnB,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe;QACpC,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;QAC3B,6EAA6E;QAC7E,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5D,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,UAAU,EAAE;aACT,KAAK,CAAC,GAAG,EAAE;YACV,iBAAiB;QACnB,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB;QACrC,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAS,WAAW;IAClB,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO;IACjC,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE;QACxB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAChC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;YACvB,iBAAiB;QACnB,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACtB,qEAAqE;IACrE,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QACvC,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAqB;IAChD,OAAO,CACL,WAAmB,EACnB,MAA8C;QAE9C,iBAAiB,EAAE,CAAC;QACpB,WAAW,EAAE,CAAC;QAEd,OAAO,IAAI,OAAO,CAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACzD,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAEtD,IAAI,MAAM,CAAC,MAAM,IAAI,eAAe,EAAE,CAAC;gBACrC,uBAAuB;gBACvB,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;oBACvB,iBAAiB;gBACnB,CAAC,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,wEAAwE;gBACxE,mBAAmB,EAAE,CAAC;YACxB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK;QACH,OAAO,WAAW,EAAE,CAAC;IACvB,CAAC;IAED,IAAI;QACF,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;CACF,CAAC;AAEF,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,8BAA8B;IAC5C,iCAAiC;IACjC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,aAAa,CAAC,MAAM,CAAC,CAAC;QACtB,MAAM,GAAG,SAAS,CAAC;IACrB,CAAC;IACD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,cAAc,CAAC,UAAU,CAAC,CAAC;QAC3B,UAAU,GAAG,SAAS,CAAC;IACzB,CAAC;IACD,UAAU,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAE/B,kEAAkE;IAClE,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IACxE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC1B,CAAC;IAED,gBAAgB,GAAG,KAAK,CAAC;AAC3B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAA0B;IACjE,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAChC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,WAAW,CAAC;IACxC,OAAO,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC"}

package/dist/memory/pipeline-manifest-sqlite.d.ts

@@ -16,6 +16,7 @@ import { docsPipelineManifest as pipelineManifest } from '../store/schema/cleo-p
 declare function getBinding(cwd?: string): Promise<import("../db/index.js").DomainBinding<import("drizzle-orm/node-sqlite/driver").NodeSQLiteDatabase<import("drizzle-orm").EmptyRelations>, import("../store/dual-scope-db.js").ProjectStore>>;
 import type { ContradictionDetail, ExtendedManifestEntry, ResearchFilter, SupersededDetail } from './index.js';
 import { filterManifestEntries } from './manifest-filter.js';
+import { type ManifestIdentityIssue } from './manifest-identity.js';
 export type ManifestEntry = ExtendedManifestEntry;
 export type { ContradictionDetail, ResearchFilter, SupersededDetail };
 export { filterManifestEntries };
@@ -84,6 +85,26 @@ export declare function readManifestEntriesSkippingMalformed(projectRoot?: strin
  * @task T12686
  */
 export declare function listMalformedManifestRows(projectRoot?: string): Promise<MalformedManifestRow[]>;
+/** A stored manifest row whose id, linked task ids or file reference fails T12829 validation. */
+export interface ManifestIdentityProblemRow {
+    /** Manifest entry id, truncated to 120 characters for display. */
+    entryId: string;
+    /** Tables holding the row (`docs_pipeline_manifest`, legacy `pipeline_manifest`). */
+    tables: string[];
+    /** The problems: `E_VALIDATION` (malformed or unsafe) or `E_NOT_FOUND` (linked task missing). */
+    issues: ManifestIdentityIssue[];
+}
+/**
+ * List every stored manifest row (archived included) whose entry id, linked
+ * task ids or file reference would be rejected by append today, and every
+ * well-formed linked task id that names no task. Read-only: the rows predate
+ * T12829 validation and are reported, never rewritten.
+ *
+ * @param projectRoot - Project root.
+ * @returns The offending rows, each with its problems.
+ * @task T12829
+ */
+export declare function listManifestIdentityProblems(projectRoot?: string): Promise<ManifestIdentityProblemRow[]>;
 /** One row a repair rewrote: its metadata before and after. */
 export interface ManifestRepairChange {
     entryId: string;
@@ -182,8 +203,22 @@ export declare function pipelineManifestPending(epicId?: string, projectRoot?: s
 export declare function pipelineManifestStats(epicId?: string, projectRoot?: string): Promise<EngineResult>;
 /** pipeline.manifest.read - Read manifest entries with optional filter */
 export declare function pipelineManifestRead(filter?: ResearchFilter, projectRoot?: string): Promise<EngineResult>;
-/** Append to canonical manifest storage after checking both histories for unresolved identities. */
-export declare function pipelineManifestAppend(entry: ExtendedManifestEntry, projectRoot?: string): Promise<EngineResult>;
+/** Options for {@link pipelineManifestAppend}. */
+export interface PipelineManifestAppendOptions {
+    /**
+     * Reject an entry whose linked task ids name no task in the project store
+     * (`E_NOT_FOUND`). The CLI/dispatch path sets it; direct SDK callers that
+     * record manifests for tasks held elsewhere may leave it off. Format checks
+     * on the id, linked task ids and file reference always run (T12829).
+     */
+    requireExistingTasks?: boolean;
+}
+/**
+ * Append to canonical manifest storage after checking both histories for
+ * unresolved identities. The entry id, linked task ids and file reference are
+ * validated first (T12829): no input can name a path outside the project.
+ */
+export declare function pipelineManifestAppend(entry: ExtendedManifestEntry, projectRoot?: string, options?: PipelineManifestAppendOptions): Promise<EngineResult>;
 /** pipeline.manifest.archive - Archive old manifest entries by date */
 export declare function pipelineManifestArchive(beforeDate: string, projectRoot?: string): Promise<EngineResult>;
 /** pipeline.manifest.compact - Dedup by contentHash (keep newest by createdAt) */
@@ -245,13 +280,20 @@ export declare function filterEntries(entries: ExtendedManifestEntry[], filter:
 export declare function distillManifestEntry(_entryId: string, _projectRoot?: string): Promise<EngineResult>;
 /**
  * Migrate existing .cleo/MANIFEST.jsonl entries into the pipeline_manifest table.
- * Skips entries that already exist (by id). Renames MANIFEST.jsonl to
- * MANIFEST.jsonl.migrated when done.
+ * Skips entries that already exist (by id). Entries whose id, linked task ids
+ * or file reference fail the T12829 identity checks are skipped, not inserted,
+ * and listed in `invalid`. Renames MANIFEST.jsonl to MANIFEST.jsonl.migrated
+ * when done.
  *
- * @returns Count of migrated and skipped entries.
+ * @returns Count of migrated and skipped entries (skipped includes invalid ones),
+ *   and every entry refused for an identity problem.
  */
 export declare function migrateManifestJsonlToSqlite(projectRoot?: string): Promise<{
     migrated: number;
     skipped: number;
+    invalid: Array<{
+        entryId: string;
+        issues: ManifestIdentityIssue[];
+    }>;
 }>;
 //# sourceMappingURL=pipeline-manifest-sqlite.d.ts.map