agentic-workflow-manager 9.19.0 → 9.20.0

package/dist/src/core/changes/receipt.js

@@ -0,0 +1,274 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFullSelection = isFullSelection;
+exports.sensorPairs = sensorPairs;
+exports.computeReceiptDigest = computeReceiptDigest;
+exports.buildReceipt = buildReceipt;
+exports.writeReceipt = writeReceipt;
+exports.readReceipt = readReceipt;
+exports.captureReceiptPrecondition = captureReceiptPrecondition;
+exports.finalizeReceipt = finalizeReceipt;
+exports.isRootManifest = isRootManifest;
+exports.finalizeRunReceipt = finalizeRunReceipt;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const atomic_file_1 = require("../atomic-file");
+const cli_version_1 = require("../cli-version");
+const paths_1 = require("../paths");
+const types_1 = require("./types");
+const text_safety_1 = require("./text-safety");
+const worktree_1 = require("./worktree");
+const RECEIPT_KEYS = ['schema', 'commit', 'ranAt', 'cliVersion', 'overall', 'sensors', 'digest'];
+const MAX_RECEIPT_BYTES = 1024 * 1024;
+/** True when the run covers every sensor: `--changed` never does, `--all` always does, `--fast` xor `--slow` is partial. */
+function isFullSelection(opts) {
+    if (opts === null || typeof opts !== 'object')
+        return false;
+    if (opts.changed)
+        return false;
+    if (opts.all)
+        return true;
+    return Boolean(opts.fast) === Boolean(opts.slow);
+}
+const byName = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * The sensors of a receipt or a record as [name, status] pairs sorted by name in UTF-16 code-unit order. JavaScript orders the keys
+ * of an object by itself (integer-like names such as '9' and '10' come first, numerically), so nothing that is digested or
+ * compared relies on that order: it goes through this array.
+ */
+function sensorPairs(sensors) {
+    return Object.entries(sensors).sort(([a], [b]) => byName(a, b));
+}
+function sortedSensors(sensors) {
+    return Object.fromEntries(sensorPairs(sensors));
+}
+/**
+ * sha256 over the canonical JSON of the receipt without its digest, `sensors` being the name-sorted pairs of sensorPairs (R2.2c).
+ * The digest is local (receipts are not versioned and are rewritten by every full run), so changing its canonical form only
+ * invalidates receipts written before it; `change new` writes and `change validate` reads the same value.
+ */
+function computeReceiptDigest(body) {
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        throw new Error((0, text_safety_1.esc)('invalid receipt: digest body must be an object'));
+    if (body.sensors === null || typeof body.sensors !== 'object' || Array.isArray(body.sensors))
+        throw new Error((0, text_safety_1.esc)('invalid receipt: digest body sensors must be an object'));
+    const canonical = JSON.stringify({
+        schema: body.schema, commit: body.commit, ranAt: body.ranAt, cliVersion: body.cliVersion,
+        overall: body.overall, sensors: sensorPairs(body.sensors),
+    });
+    return 'sha256:' + crypto_1.default.createHash('sha256').update(canonical).digest('hex');
+}
+/**
+ * The ONE receipt shape check, shared by build, write and read so that nothing is written that cannot be read back.
+ * Returns a static description of the first problem (never echoes the offending value), or null when the receipt is pristine.
+ */
+function receiptProblem(x) {
+    if (x === null || typeof x !== 'object' || Array.isArray(x))
+        return 'receipt must be an object';
+    const r = x;
+    const keys = Object.keys(r);
+    if (keys.length !== RECEIPT_KEYS.length || !RECEIPT_KEYS.every((k) => k in r))
+        return 'receipt must have exactly the schema keys';
+    if (r.schema !== 1)
+        return 'schema must be 1';
+    if (!(0, types_1.isCommitId)(r.commit))
+        return 'commit must be 40 or 64 lowercase hex characters';
+    if (!(0, text_safety_1.isCanonicalIso)(r.ranAt))
+        return 'ranAt must be a canonical ISO timestamp';
+    if (!(0, text_safety_1.isSingleLine)(r.cliVersion))
+        return 'cliVersion must be a single line';
+    if (!(0, types_1.isOverall)(r.overall))
+        return 'overall is not a known verdict';
+    const sensors = r.sensors;
+    if (sensors === null || typeof sensors !== 'object' || Array.isArray(sensors))
+        return 'sensors must be an object';
+    for (const [name, status] of Object.entries(sensors)) {
+        if (!(0, types_1.isSensorName)(name))
+            return `sensor names must be a single line of 1 to ${types_1.MAX_SENSOR_NAME} characters`;
+        if (!(0, types_1.isSensorStatus)(status))
+            return 'a sensor status is not a known status';
+    }
+    if (typeof r.digest !== 'string')
+        return 'digest must be a string';
+    const { digest, ...body } = r;
+    if (computeReceiptDigest(body) !== digest)
+        return 'digest does not match the content';
+    return null;
+}
+/** Builds a receipt and fails closed: throws an Error naming the problem when the result is not one `readReceipt` would accept. */
+function buildReceipt(input) {
+    const out = input === null || typeof input !== 'object' ? undefined : input.output;
+    if (out === null || typeof out !== 'object' || !Array.isArray(out.sensors) || out.sensors.some((s) => s === null || typeof s !== 'object')) {
+        throw new Error('invalid receipt: run output must carry a sensors array');
+    }
+    const sensors = sortedSensors(Object.fromEntries(out.sensors.map((s) => [s.name, s.status])));
+    const body = { schema: 1, commit: input.commit, ranAt: input.ranAt, cliVersion: input.cliVersion, overall: out.overall, sensors };
+    const receipt = { ...body, digest: computeReceiptDigest(body) };
+    const problem = receiptProblem(receipt);
+    if (problem !== null)
+        throw new Error(`invalid receipt: ${problem}`);
+    return receipt;
+}
+function runsDir(root) {
+    return path_1.default.join(root, '.awm', 'sensors', 'runs');
+}
+const RUNS_IGNORE_FILE = '.gitignore';
+const RUNS_IGNORE_CONTENT = '*\n';
+/**
+ * R2.2b: receipts are local and never versioned, so the directory ignores itself (`*` also covers this file): `git add -A` in a
+ * repository that does not ignore `.awm` can then never commit them. Idempotent; a link at the target is refused (writeFileAtomic).
+ */
+function ensureRunsIgnore(root) {
+    const file = path_1.default.join(runsDir(root), RUNS_IGNORE_FILE);
+    try {
+        const stat = fs_1.default.lstatSync(file);
+        if (stat.isFile() && fs_1.default.readFileSync(file, 'utf8') === RUNS_IGNORE_CONTENT)
+            return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    (0, atomic_file_1.writeFileAtomic)(file, RUNS_IGNORE_CONTENT, 0o644);
+}
+function assertNoSymlinkChain(root) {
+    let current = root;
+    for (const segment of ['.awm', 'sensors', 'runs']) {
+        current = path_1.default.join(current, segment);
+        try {
+            if (fs_1.default.lstatSync(current).isSymbolicLink())
+                throw new Error(`refusing to use symlinked path ${(0, text_safety_1.esc)(current)}`);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+}
+/** Writes a receipt. Validates with the same check `readReceipt` applies BEFORE touching the filesystem; throws an Error (never a raw TypeError). */
+function writeReceipt(root, receipt) {
+    if (typeof root !== 'string' || root.length === 0)
+        throw new Error('receipt root must be a non-empty string');
+    const problem = receiptProblem(receipt);
+    if (problem !== null)
+        throw new Error(`invalid receipt: ${problem}`);
+    const content = JSON.stringify(receipt, null, 2) + '\n';
+    if (Buffer.byteLength(content) > MAX_RECEIPT_BYTES)
+        throw new Error('invalid receipt: larger than the size readReceipt accepts');
+    assertNoSymlinkChain(root);
+    fs_1.default.mkdirSync(runsDir(root), { recursive: true, mode: 0o700 });
+    assertNoSymlinkChain(root);
+    ensureRunsIgnore(root);
+    const file = path_1.default.join(runsDir(root), `${receipt.commit}.json`);
+    (0, atomic_file_1.writeFileAtomic)(file, content, 0o600);
+    // writeFileAtomic keeps the mode of a file it replaces; a receipt is always owner-only.
+    fs_1.default.chmodSync(file, 0o600);
+    return file;
+}
+const INVALID = { ok: false, code: 'receipt-invalid' };
+/** Reads and verifies a receipt. Anything that is not a pristine, digest-matching receipt for `commit` reads as invalid (or missing). */
+function readReceipt(root, commit) {
+    if (typeof root !== 'string' || root.length === 0 || !(0, types_1.isCommitId)(commit))
+        return INVALID;
+    let raw;
+    try {
+        assertNoSymlinkChain(root);
+        const file = path_1.default.join(runsDir(root), `${commit}.json`);
+        const stat = fs_1.default.lstatSync(file);
+        // lstat does not follow links, so a symlink is simply "not a file".
+        if (!stat.isFile() || stat.size > MAX_RECEIPT_BYTES)
+            return INVALID;
+        raw = fs_1.default.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? { ok: false, code: 'receipt-missing' } : INVALID;
+    }
+    let x;
+    try {
+        x = JSON.parse(raw);
+    }
+    catch {
+        return INVALID;
+    }
+    if (receiptProblem(x) !== null || x.commit !== commit)
+        return INVALID;
+    const receipt = x;
+    return { ok: true, receipt };
+}
+/** Measured BEFORE the run: a receipt certifies a commit only when the tree equals it. */
+function captureReceiptPrecondition(cwd) {
+    if (typeof cwd !== 'string' || cwd.length === 0)
+        return { eligible: false, reason: 'cwd must be a non-empty string' };
+    const state = (0, worktree_1.gitState)(cwd, true);
+    if (state.kind === 'not-repo')
+        return { eligible: false, reason: worktree_1.REASON_NOT_REPO };
+    if (state.kind === 'failed')
+        return { eligible: false, reason: worktree_1.REASON_GIT_FAILED };
+    if (state.dirty)
+        return { eligible: false, reason: 'working tree has uncommitted changes (commit them first)' };
+    if (!(0, types_1.isCommitId)(state.commit))
+        return { eligible: false, reason: 'HEAD is not a full commit id' };
+    return { eligible: true, root: state.root, commit: state.commit };
+}
+/** Returns '' on success, or one stderr line explaining why no receipt was written. Never throws. */
+function finalizeReceipt(pre, output, deps = {}) {
+    try {
+        if (pre === null || typeof pre !== 'object')
+            return 'no sensor receipt written: precondition was not captured\n';
+        if (!pre.eligible)
+            return `no sensor receipt written: ${(0, text_safety_1.esc)(pre.reason)}\n`;
+        const after = (0, worktree_1.gitState)(pre.root, false);
+        if (after.kind === 'failed')
+            return `no sensor receipt written: ${worktree_1.REASON_GIT_FAILED}\n`;
+        if (after.kind === 'not-repo')
+            return `no sensor receipt written: ${worktree_1.REASON_NOT_REPO}\n`;
+        if (after.commit !== pre.commit || after.dirty)
+            return 'no sensor receipt written: HEAD or tracked files changed during the run\n';
+        writeReceipt(pre.root, buildReceipt({ commit: pre.commit, ranAt: (deps.now ?? (() => new Date()))().toISOString(), cliVersion: (deps.version ?? cli_version_1.cliVersion)(), output }));
+        return '';
+    }
+    catch (error) {
+        return `no sensor receipt written: ${(0, text_safety_1.esc)(error instanceof Error ? error.message : String(error))}\n`;
+    }
+}
+/** True when `manifestPath` is the repository root's `.awm/sensors.json` (identity through realpath.native, see sameExistingPath; a missing file is not it). */
+function isRootManifest(root, manifestPath) {
+    if (typeof root !== 'string' || root.length === 0 || typeof manifestPath !== 'string' || manifestPath.length === 0)
+        return false;
+    return (0, paths_1.sameExistingPath)(path_1.default.join(root, '.awm', 'sensors.json'), manifestPath);
+}
+/**
+ * R2.2b/R2.2c: the receipt of a `sensors run`. On top of finalizeReceipt, a receipt certifies the WHOLE declared sensor set or
+ * nothing: none is written when no sensor ran (an empty list), when the run dropped part of the manifest (schema-invalid entries,
+ * pack drift), when the verdict is `not_certified`, nor when the manifest that ran is not the repository root's (a receipt is
+ * keyed by commit only, so the manifests of a monorepo's packages would overwrite each other). Returns '' on success, or one
+ * stderr line that says which case applies. Never throws.
+ */
+function finalizeRunReceipt(pre, output, deps = {}) {
+    try {
+        if (pre === null || typeof pre !== 'object' || !pre.eligible)
+            return finalizeReceipt(pre, output, deps);
+        const withheld = (why) => `no sensor receipt written: ${why}\n`;
+        if (output === null || typeof output !== 'object' || !Array.isArray(output.sensors) || output.sensors.length === 0)
+            return withheld('no sensor ran, so there is nothing to certify');
+        if (output.sensors.every((sensor) => sensor !== null && typeof sensor === 'object' && sensor.status === 'skipped'))
+            return withheld('every sensor was skipped, so the run certified nothing');
+        if (Array.isArray(output.invalidEntries) && output.invalidEntries.length > 0)
+            return withheld('some sensor entries of the manifest were invalid and skipped, so the verdict does not cover it');
+        if (output.packDrift !== undefined && output.packDrift !== null)
+            return withheld('the manifest is on the generic fallback while the tree has real stack indicators (pack drift)');
+        if (output.overall === 'not_certified')
+            return withheld('the verdict was not certified (not_certified)');
+        if (!isRootManifest(pre.root, output.manifestPath))
+            return withheld("the manifest that ran is not the repository root's .awm/sensors.json (a receipt certifies a whole commit)");
+        return finalizeReceipt(pre, output, deps);
+    }
+    catch (error) {
+        return `no sensor receipt written: ${(0, text_safety_1.esc)(error instanceof Error ? error.message : String(error))}\n`;
+    }
+}

package/dist/src/core/changes/record-io.js

@@ -0,0 +1,149 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorCode = void 0;
+exports.inspectRecordDir = inspectRecordDir;
+exports.createRecordDir = createRecordDir;
+exports.recordsWithSlug = recordsWithSlug;
+exports.readRecord = readRecord;
+exports.unchangedSince = unchangedSince;
+exports.createExclusive = createExclusive;
+exports.replaceRecord = replaceRecord;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const atomic_file_1 = require("../atomic-file");
+const parse_1 = require("./parse");
+const text_safety_1 = require("./text-safety");
+const types_1 = require("./types");
+// Filesystem access to `docs/changes/`: the one place that decides what is safe to read from and write to. Nothing here throws
+// (failures come back as a value), no link is ever followed on purpose, and text from the filesystem is escaped before it is
+// put into a message.
+const errorCode = (error) => ((0, text_safety_1.isObj)(error) && typeof error.code === 'string' ? error.code : 'unknown');
+exports.errorCode = errorCode;
+/** What one path component is, without following links: a real directory, nothing, or something that must not be used. */
+function classify(target) {
+    try {
+        const stat = fs_1.default.lstatSync(target);
+        return stat.isSymbolicLink() || !stat.isDirectory() ? 'unsafe' : 'dir';
+    }
+    catch (error) {
+        return (0, exports.errorCode)(error) === 'ENOENT' ? 'absent' : 'error';
+    }
+}
+/** Walks `docs` and `docs/changes` one level at a time: a link or a non-directory on the way is unsafe. */
+function inspectRecordDir(root) {
+    let current = root;
+    for (const segment of types_1.RECORD_DIR.split('/')) {
+        current = path_1.default.join(current, segment);
+        const level = classify(current);
+        if (level !== 'dir')
+            return level === 'absent' ? { kind: 'absent' } : { kind: level };
+    }
+    return { kind: 'ok', dir: current };
+}
+/**
+ * Creates what is missing, one level at a time, and checks each level right after it was made: a link planted in place of
+ * `docs` is seen before `changes` is created inside it, so nothing is ever created through a link.
+ */
+function createRecordDir(root) {
+    let current = root;
+    for (const segment of types_1.RECORD_DIR.split('/')) {
+        current = path_1.default.join(current, segment);
+        try {
+            fs_1.default.mkdirSync(current);
+        }
+        catch (error) {
+            if ((0, exports.errorCode)(error) !== 'EEXIST')
+                return { kind: 'error' };
+        }
+        const level = classify(current);
+        if (level !== 'dir')
+            return { kind: level === 'absent' ? 'error' : level };
+    }
+    return { kind: 'ok', dir: current };
+}
+/** Names of the records with this slug, whatever their date (a directory entry named like a record counts). Null when the directory cannot be listed. */
+function recordsWithSlug(dir, slug) {
+    try {
+        return fs_1.default.readdirSync(dir).filter((name) => parse_1.RECORD_FILE_RE.exec(name)?.[4] === slug);
+    }
+    catch {
+        return null;
+    }
+}
+const unreadable = (code, message, extras = {}) => ({ ok: false, code, message, ...extras });
+/**
+ * Reads a record for a rewrite: a regular file (not a link), within the record size limit, valid UTF-8 so that it can be written
+ * back byte for byte. `ignoreBOM: true` keeps a leading BOM in the text as U+FEFF (the default would strip it, and the rewrite
+ * would drop it silently); the record then does not start with `---` and fails as invalid.
+ */
+function readRecord(target, name) {
+    const label = (0, text_safety_1.esc)(name);
+    try {
+        const stat = fs_1.default.lstatSync(target);
+        if (stat.isSymbolicLink())
+            return unreadable('unsafe-path', `${label} is a symlink; refusing to write`);
+        if (!stat.isFile())
+            return unreadable('record-invalid', `${label} is not a regular file`);
+        if (stat.size > types_1.MAX_RECORD_BYTES)
+            return unreadable('record-invalid', `${label} is larger than ${types_1.MAX_RECORD_BYTES} bytes`, { tooLarge: true });
+        const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(fs_1.default.readFileSync(target));
+        return { ok: true, text, snapshot: { size: stat.size, mtimeMs: stat.mtimeMs, ino: stat.ino } };
+    }
+    catch (error) {
+        const code = (0, exports.errorCode)(error);
+        return code === 'ERR_ENCODING_INVALID_ENCODED_DATA' ? unreadable('record-invalid', `${label} is not valid UTF-8`) : unreadable('io-failed', `could not read ${label} (${(0, text_safety_1.esc)(code)})`);
+    }
+}
+/** True only when the path is still a regular file (not a link) with the size, modification time and inode it had when it was read. */
+function unchangedSince(target, snapshot) {
+    try {
+        const stat = fs_1.default.lstatSync(target);
+        if (!stat.isFile() || stat.size !== snapshot.size || stat.mtimeMs !== snapshot.mtimeMs)
+            return false;
+        // An inode number can be 0 or imprecise on some Windows file systems: compare only when both sides carry one.
+        return stat.ino === 0 || snapshot.ino === 0 || stat.ino === snapshot.ino;
+    }
+    catch {
+        return false;
+    }
+}
+/** Exclusive create: never replaces a file, never follows a link at the target. Removes what it created when the write fails. */
+function createExclusive(file, content) {
+    let fd;
+    try {
+        fd = fs_1.default.openSync(file, 'wx', 0o644);
+    }
+    catch (error) {
+        return (0, exports.errorCode)(error) === 'EEXIST' ? 'exists' : 'error';
+    }
+    try {
+        fs_1.default.writeFileSync(fd, content, 'utf8');
+        fs_1.default.fsyncSync(fd);
+        fs_1.default.closeSync(fd);
+        return 'ok';
+    }
+    catch {
+        try {
+            fs_1.default.closeSync(fd);
+        }
+        catch { /* the write error is the one that matters */ }
+        try {
+            fs_1.default.unlinkSync(file);
+        }
+        catch { /* best effort: the file is ours, and incomplete */ }
+        return 'error';
+    }
+}
+/** Atomic replacement of an existing record (temporary file + rename, mode kept; a link at the target is refused). */
+function replaceRecord(target, content) {
+    try {
+        (0, atomic_file_1.writeFileAtomic)(target, content, 0o644);
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, code: (0, exports.errorCode)(error) };
+    }
+}

package/dist/src/core/changes/render-list.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_SCHEMA = void 0;
+exports.renderJson = renderJson;
+exports.renderText = renderText;
+exports.renderVoice = renderVoice;
+const list_parse_1 = require("./list-parse");
+const text_safety_1 = require("./text-safety");
+// The three renderings of `awm changes list` (R5.6). The result already holds clean values (list.ts escapes what git printed);
+// the text and voice lines are cleaned again here, so each stays one line whatever a caller hands in. Nothing here throws.
+const INVALID_TEXT = 'invalid-input: not a list result\n';
+const MAX_VOICE_LINE = 600;
+const MAX_TITLE = 200;
+/** R5.6: the first key of the JSON, so a consumer can tell which contract it is reading. */
+exports.LIST_SCHEMA = 'awm.changes-list/v1';
+const usable = (r) => (0, text_safety_1.isObj)(r) && Array.isArray(r.changes) && typeof r.base === 'string' && typeof r.since === 'string';
+const count = (n) => (typeof n === 'number' && Number.isSafeInteger(n) && n >= 0 ? n : 0);
+const isValid = (r) => (0, text_safety_1.isObj)(r) && !('diagnostics' in r);
+const clipVoice = (line) => (line.length <= MAX_VOICE_LINE ? line : `${(0, text_safety_1.sliceNoSplit)(line, MAX_VOICE_LINE - 1)}…`);
+/** The repository name: the last segment of host/owner/name, else the fallback (the directory name). */
+function repoName(result, fallback) {
+    const last = typeof result.repo === 'string' ? result.repo.split('/').pop() : '';
+    return (0, list_parse_1.cleanLine)(last || fallback, 100);
+}
+function renderJson(result) {
+    try {
+        if (!usable(result))
+            return '{"error":"invalid-input"}\n';
+        const changes = result.changes.map((c) => ({ sha: c.sha, subject: c.subject, classification: c.classification, merged_at: c.merged_at, pr: c.pr, release: c.release, records: c.records }));
+        return `${JSON.stringify({ schema: exports.LIST_SCHEMA, repo: result.repo, base: result.base, since: result.since, adopted: result.adopted, truncated: result.truncated, omitted: result.omitted, changes })}\n`;
+    }
+    catch {
+        return '{"error":"invalid-input"}\n';
+    }
+}
+const header = ['WHEN'.padEnd(16), 'CLASSIFICATION'.padEnd(14), 'SHA'.padEnd(8), 'PR'.padEnd(6), 'CHANGE'].join('  ');
+function textRow(c) {
+    const first = c.records[0];
+    const title = first !== undefined && isValid(first) ? first.title : c.subject;
+    // The first FAILING record of an invalid-record commit (the valid ones carry an empty diagnostics list).
+    const failing = c.records.find((r) => Array.isArray(r.diagnostics) && r.diagnostics.length > 0);
+    const diagnostic = failing !== undefined && !isValid(failing) ? failing.diagnostics[0] : undefined;
+    const when = c.merged_at === null ? 'unknown' : String(c.merged_at).slice(0, 16).replace('T', ' ');
+    const cells = [
+        (0, list_parse_1.cleanLine)(when, 16).padEnd(16),
+        (0, list_parse_1.cleanLine)(c.classification, 14).padEnd(14),
+        (0, list_parse_1.cleanLine)(String(c.sha).slice(0, 8), 8).padEnd(8),
+        (c.pr === null ? '-' : (0, list_parse_1.cleanLine)(`#${c.pr}`, 12)).padEnd(6),
+        `${(0, list_parse_1.cleanLine)(title, MAX_TITLE)}${c.release ? `  [${(0, list_parse_1.cleanLine)(c.release, 255)}]` : ''}${diagnostic ? `  (${(0, list_parse_1.cleanLine)(diagnostic.code, 64)})` : ''}`,
+    ];
+    return (0, text_safety_1.clipMessage)(cells.join('  '));
+}
+function renderText(result, fallbackName) {
+    try {
+        if (!usable(result))
+            return INVALID_TEXT;
+        const name = repoName(result, fallbackName);
+        const base = (0, list_parse_1.cleanLine)(result.base, 255);
+        if (result.adopted === false)
+            return `${(0, text_safety_1.clipMessage)(`${name} has not adopted Change Records (no record under docs/changes/ on ${base}).`)}\n`;
+        if (result.changes.length === 0)
+            return `${(0, text_safety_1.clipMessage)(`No changes on ${base} since ${(0, list_parse_1.cleanLine)(result.since, 40)}.`)}\n`;
+        const lines = [(0, text_safety_1.clipMessage)(header), ...result.changes.map(textRow)];
+        if (result.truncated)
+            lines.push(`... ${count(result.omitted)} older change(s) not shown; narrow --since to see them.`);
+        return `${lines.join('\n')}\n`;
+    }
+    catch {
+        return INVALID_TEXT;
+    }
+}
+/** The summary as a sentence: it ends in one of . ! ? … (a period is added when it does not). */
+function spoken(summary) {
+    const s = (0, list_parse_1.cleanLine)(summary, 280);
+    return s !== '' && '.!?…'.includes(s[s.length - 1]) ? s : `${s}.`;
+}
+function sentence(name, r) {
+    const pending = Array.isArray(r.manual_validation) ? r.manual_validation.length : 0;
+    const verified = (0, text_safety_1.isObj)(r.verification) && r.verification.overall === 'pass' ? 'verificado' : 'sin verificar';
+    return clipVoice(`${name}: ${spoken(r.summary_short)} ${(0, list_parse_1.cleanLine)(r.type, 64)}, ${verified}, ${pending} validaciones manuales pendientes.`);
+}
+function renderVoice(result, fallbackName) {
+    try {
+        if (!usable(result))
+            return INVALID_TEXT;
+        const name = repoName(result, fallbackName);
+        if (result.adopted === false)
+            return `${clipVoice(`${name}: todavía no usa Change Records.`)}\n`;
+        if (result.changes.length === 0)
+            return `${clipVoice(`${name}: sin cambios desde ${(0, list_parse_1.cleanLine)(result.since.slice(0, 10), 10)}.`)}\n`;
+        const lines = [];
+        for (const c of result.changes) {
+            if (c.classification !== 'recorded')
+                continue;
+            for (const r of c.records)
+                if (isValid(r))
+                    lines.push(sentence(name, r));
+        }
+        const missing = result.changes.filter((c) => c.classification === 'missing').length;
+        const invalid = result.changes.filter((c) => c.classification === 'invalid-record').length;
+        lines.push(`Además: ${missing} cambio(s) sin record y ${invalid} con record inválido.`);
+        if (result.truncated)
+            lines.push(`Hay ${count(result.omitted)} cambio(s) más antiguo(s) sin mostrar; acota el período.`);
+        return `${lines.join('\n')}\n`;
+    }
+    catch {
+        return INVALID_TEXT;
+    }
+}