@ansonlai/docx-redline-js 0.5.4 → 0.6.0

package/docs/TESTING.md

@@ -22,7 +22,10 @@ fixtures rarely contain.
 | Multimodal LLM visual spot check | On-demand / sampled | Evaluates rendered real-document pages with vision models for layout, table alignment, and typography regressions | Full-corpus automated coverage (intentionally decoupled and sampled due to cost/time) |
 | XSD and LibreOffice | See [Release validation and independent oracles](#release-validation-and-independent-oracles) | Schema conformance and acceptance by a second consumer | Word-specific revision semantics |
 | Agent inspection and package facade | `node tests/document_inspection_tests.mjs`, `node tests/docx_package_facade_tests.mjs` | Canonical text, comment/list resolution, package-scoped IDs, untouched-part preservation, and atomic rollback | Desktop Word rendering |
-| Agent CLI | `node tests/agent_cli_tests.mjs` | JSON contracts, exact-text extraction, author requirements, safe output behavior, all command families, and operation-schema readability | Cross-platform CI beyond the current runner |
+| Agent CLI | `node tests/agent_cli_tests.mjs`, `node tests/agent_cli_protocol_tests.mjs` | JSON contracts, exact-text extraction, stdin operations, named agent-profile defaults, UTF-8 fidelity, complete-success exits, source safety, all command families, and operation-schema readability | Cross-platform CI beyond the current runner |
+| Example agent session | `node tests/agent_session_example_tests.mjs`, `node tests/localized_edit_example_tests.mjs` | A non-package sample wrapper delegates to the Node facade, binds and refreshes opaque handles across package revisions, returns context windows, compiles exact localized edits, preserves accepted/rejected lifecycle and atomic rollback, and supports review resolution | LLM/provider latency or a production tool-server transport |
+| Batch compilation and recovery | `node tests/batch_source_binding_tests.mjs`, `node tests/error_recovery_contract_tests.mjs`, `node tests/capture_dependency_graph_tests.mjs` | Batch-start source identity survives structural index drift and savepoint restoration; true overlap and capture fan-out fail before mutation; recovery envelopes, retry bases, bounded CLI diagnostics, and complete-success exits remain stable | Whether a model follows the returned recovery action correctly |
+| Agent documentation contract | `node tests/agent_documentation_contract_tests.mjs` | The ordinary fast start stays within its 40–60 line/600-word budget, retains required safety contracts, and the launch card routes to detailed sources while the development wrapper stays outside package files | Whether a particular model reads or follows the instructions |
 | Agent edge cases | `node tests/canonical_paragraph_text_tests.mjs`, `node tests/document_inspection_edge_tests.mjs`, `node tests/docx_package_transaction_edge_tests.mjs`, `node tests/node_zip_archive_tests.mjs`, `node tests/agent_cli_edge_tests.mjs` | Revision-view semantics, cross-paragraph anchors, nested numbering, transaction reuse, multi-author cleanup, malformed ZIP handling, and destructive CLI safeguards | Desktop Word rendering and non-Windows CI |
 | Performance boundary regression | `node tests/performance_phase2_boundary_tests.mjs` | Stable facade re-exports, leaf imports, session rollback, isolated context commit, and comment-first scheduling | The Phase 1 one-parse/one-serialize performance target |
 | Live-session accuracy and instrumentation | `node tests/performance_phase1_session_tests.mjs` | One full parse/serialization, sequential semantic equivalence, exact accepted/rejected text, valid revisions, list/table/comment/highlight preservation, savepoint no-ops, and zero-serialization rollback | Desktop Word rendering |
@@ -79,6 +82,22 @@ not correctness gates. Per-operation DOM savepoints are retained because
 redline accuracy, no-op isolation, and rollback fidelity take precedence over
 the aspirational speed target.
 
+Run the observational agent-protocol benchmark with:
+
+```powershell
+npm run benchmark:agent
+```
+
+It writes `tmp/benchmarks/agent-workflow-latest.json` and compares canonical
+stateless Node, legacy file-based CLI, compact stdin/profile CLI, and the
+development-only session example. It records native/in-process CLI time, heap,
+serialized request bytes, protocol calls, instruction words/bytes, exact
+accepted/rejected text, comment preservation, ordering, recovery, and
+cross-author attribution. It does not measure or estimate LLM reasoning, exact
+tokens, tool transport, Claude, or OpenCode wall time; collect those separately
+in the calling harness. The checked WP-07 results are summarized in the
+[agent protocol rollout audit](validation-reports/2026-09-12-agent-protocol-rollout.md).
+
 ## Cross-author revision slicing test suite
 
 The cross-author revision slicing subsystem introduces six complementary test lanes:

package/docs/schemas/document-operations.schema.json

@@ -48,7 +48,11 @@
             "index": { "type": ["integer", "string"] }, "paragraphIndex": { "type": ["integer", "string"] },
             "paragraphId": { "type": "string" }, "occurrence": { "type": "integer", "minimum": 1 },
             "inTable": { "type": "boolean" }, "fingerprint": { "type": "string" }, "sourceFingerprint": { "type": "string" },
-            "revisionView": { "type": "string", "enum": ["accepted", "rejected"] },
+            "revisionView": {
+              "type": "string",
+              "enum": ["accepted", "rejected"],
+              "description": "Defaults to rejected for restore operations and accepted for other operation types."
+            },
             "captureRef": { "type": "string", "minLength": 1, "maxLength": 256 },
             "select": { "type": "string", "minLength": 1 }
           },

package/docs/validation-reports/2026-09-12-agent-protocol-rollout.md

@@ -0,0 +1,82 @@
+# Agent Protocol Rollout Audit
+
+**Date:** 2026-09-12  
+**Scope:** WP-06 shell/documentation work and WP-07 repository-level rollout  
+**Benchmark:** `npm run benchmark:agent` on Node v24.11.1 / Windows x64,
+7 measured iterations after 2 warmups
+
+## Outcome
+
+The compact shell path removes the operations-file tool turn, and the
+development session example removes repeated target/policy payload. All measured
+paths produced the requested accepted view, restored the exact source text in
+the rejected view, passed package/revision validation, and preserved comment
+content. These are protocol and native-runtime measurements; no LLM/provider
+latency or token count was estimated.
+
+| Measure | Legacy | WP-06/07 result |
+|---|---:|---:|
+| Ordinary agent instructions | 2,023 words | 349 words (82.75% reduction) |
+| Repository launch card | 2,023 words | 527 words |
+| Shell workflow calls | extract + file write + apply (3) | extract + stdin apply (2; 33.33% reduction) |
+| Independent early-split permutations | one previously order-sensitive direction | both directions succeed |
+
+## Measured workflow results
+
+Median wall time includes the in-process CLI file/stdin transport for CLI rows.
+It does not include process startup, a model, provider tokenization, or tool
+transport.
+
+| Case | Legacy CLI | Compact stdin CLI | Session example | Session request bytes vs legacy |
+|---|---:|---:|---:|---:|
+| Terminal punctuation | 49.63 ms | 46.05 ms | 49.50 ms | 125 vs 255 (50.98% fewer) |
+| Term-duration phrase | 55.50 ms | 51.30 ms | 56.05 ms | 128 vs 630 (79.68% fewer) |
+| Simple mutuality | 62.82 ms | 50.22 ms | 58.45 ms | 281 vs 935 (69.95% fewer) |
+| Full-clause rewrite | 50.55 ms | 50.31 ms | 53.81 ms | 223 vs 407 (45.21% fewer) |
+| Comment + redline | 71.94 ms | 62.11 ms | 63.81 ms | 290 vs 724 (59.94% fewer) |
+
+Compared with the canonical stateless Node request envelope, localized session
+requests remained 86.11% smaller for punctuation, 89.96% smaller for a duration
+change, and 82.22% smaller for deterministic mutuality. A complete clause
+rewrite is naturally less compressible and is not presented as a localized-edit
+win.
+
+## Fidelity and recovery audit
+
+- The benchmark validates accepted and rejected paragraph text for every text
+  edit and verifies the mixed-batch comment definition remains present.
+- Both ten-edit permutations around an early paragraph split complete without
+  target errors.
+- An ambiguous target returns two candidates without auto-selection.
+- A stale session handle returns `STALE_TARGET_HANDLE` with recovery action
+  `reinspect`.
+- The default cross-author policy refuses the edit with `EXISTING_REVISIONS`.
+  `slice-cross-author` succeeds while retaining both original authors (Anson
+  Lai and John Doe), and rejecting the benchmark author's work still retains
+  those authors.
+- The CLI protocol regression proves UTF-8 stdin transport, package-revision
+  enforcement, source immutability, agent-profile defaults, atomic rollback,
+  progressive exit code 3, and rejected-view restoration.
+
+## Configuration decision
+
+No project or auto-discovered configuration file was added. The CLI already
+defaults author, strict targeting, validation, tracked changes, revision safety,
+and output naming. The explicit `--profile agent` flag captures the remaining
+atomic/complete-success policy and reports `effectiveOptions`. Removing that one
+flag would not justify hidden configuration discovery or precedence reasoning.
+
+## Remaining external measurement
+
+Claude/OpenCode wall time, prompt tokens, generated tokens, and provider tool
+latency must be captured by those calling harnesses. The repository benchmark
+records bytes, words, calls, native time, failure behavior, and document
+fidelity so those external observations can be compared without conflating the
+library with model reasoning.
+
+## Automated verification
+
+- `npm test`: 107 passed, 0 failed.
+- `npm run check:types`: 123 runtime exports have declarations.
+- `npm run test:isolation`: core dependency and Word-API isolation passed.
+- Focused ESLint for all WP-06/07 source, benchmark, and test files passed.

package/engine/oxml-engine.js

@@ -28,7 +28,8 @@ import { applySurgicalMode } from './surgical-mode.js';
 import { applyReconstructionMode } from './reconstruction-mode.js';
 import { applyTableReconciliation, applyTextToTableTransformation } from './table-mode.js';
 import { getDefaultAuthor } from '../adapters/config.js';
-import { containsTrackedChanges, getTrackedChangeAuthors, withOoxmlSourceType } from '../core/word-xml.js';
+import { containsTrackedChanges, createWordElement, getTrackedChangeAuthors, withOoxmlSourceType } from '../core/word-xml.js';
+import { clonePropertiesWithoutRevisionHistory } from '../core/revision-cloning.js';
 import {
     NS_W,
     RevisionIdAllocator,
@@ -52,6 +53,62 @@ function getCommentIdsInOoxml(node) {
     }
     return [...ids].sort((a, b) => Number(a) - Number(b) || a.localeCompare(b));
 }
+
+function directWordChild(node, localName) {
+    return Array.from(node?.childNodes || []).find(child => (
+        child?.nodeType === 1
+        && child.namespaceURI === NS_W
+        && child.localName === localName
+    )) || null;
+}
+
+function insertedParagraphMarkMetadata(paragraph, author) {
+    const marker = directWordChild(directWordChild(directWordChild(paragraph, 'pPr'), 'rPr'), 'ins');
+    if (!marker) return null;
+    const markerAuthor = marker.getAttribute('w:author') || marker.getAttributeNS(NS_W, 'author') || '';
+    if (markerAuthor.trim().toLowerCase() !== String(author || '').trim().toLowerCase()) return null;
+    return {
+        id: marker.getAttribute('w:id') || marker.getAttributeNS(NS_W, 'id') || '',
+        author: markerAuthor,
+        date: marker.getAttribute('w:date') || marker.getAttributeNS(NS_W, 'date') || ''
+    };
+}
+
+function emptyParagraphBaseline(paragraph, serializer) {
+    const clone = paragraph.cloneNode(false);
+    const pPr = directWordChild(paragraph, 'pPr');
+    if (pPr) clone.appendChild(clonePropertiesWithoutRevisionHistory(pPr));
+    return serializer.serializeToString(clone);
+}
+
+function restoreInsertedParagraphMark(oxml, metadata) {
+    if (!metadata || typeof oxml !== 'string' || !oxml.trim()) return oxml;
+    const parsed = parseOoxmlSafe(oxml, 'text/xml');
+    if (!parsed.doc || parsed.error) return oxml;
+    const paragraph = parsed.doc.documentElement?.localName === 'p'
+        ? parsed.doc.documentElement
+        : getDocumentParagraphs(parsed.doc)[0];
+    if (!paragraph) return oxml;
+
+    let pPr = directWordChild(paragraph, 'pPr');
+    if (!pPr) {
+        pPr = createWordElement(parsed.doc, 'w:pPr');
+        paragraph.insertBefore(pPr, paragraph.firstChild);
+    }
+    let rPr = directWordChild(pPr, 'rPr');
+    if (!rPr) {
+        rPr = createWordElement(parsed.doc, 'w:rPr');
+        pPr.appendChild(rPr);
+    }
+    if (!directWordChild(rPr, 'ins')) {
+        const marker = createWordElement(parsed.doc, 'w:ins');
+        if (metadata.id) marker.setAttribute('w:id', metadata.id);
+        marker.setAttribute('w:author', metadata.author);
+        if (metadata.date) marker.setAttribute('w:date', metadata.date);
+        rPr.appendChild(marker);
+    }
+    return serializeXml(parsed.doc);
+}
 
 /**
  * Applies redline track changes to OOXML by modifying the DOM in-place.
@@ -77,11 +134,12 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
     const serializer = createSerializer();
     let parseWarnings = [];
     const operationWarnings = [];
-    let normalizedExistingRevisions = false;
+    let normalizedExistingRevisions = false;
+    let preservedInsertedParagraphMark = null;
     const existingRevisionsPolicy = options.existingRevisions || 'merge-same-author';
     const keepNormalizedNoOp = existingRevisionsPolicy === 'accept-all-first-keep-normalized';
-    const finalize = result => {
-        const withStatus = { ...result };
+    const finalize = result => {
+        const withStatus = { ...result };
         if (normalizedExistingRevisions && withStatus.hasChanges === false && withStatus.status !== 'error') {
             if (existingRevisionsPolicy === 'merge-same-author' || existingRevisionsPolicy === 'slice-cross-author') {
                 withStatus.oxml = workingOoxml;
@@ -105,10 +163,13 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
         if (warnings.length > 0) {
             withStatus.warnings = [...new Set(warnings)];
         }
-        if (!withStatus.status) {
-            withStatus.status = withStatus.hasChanges ? 'ok' : 'no-op';
-        }
-        return withOoxmlSourceType(withStatus);
+        if (!withStatus.status) {
+            withStatus.status = withStatus.hasChanges ? 'ok' : 'no-op';
+        }
+        if (preservedInsertedParagraphMark && withStatus.hasChanges && typeof withStatus.oxml === 'string') {
+            withStatus.oxml = restoreInsertedParagraphMark(withStatus.oxml, preservedInsertedParagraphMark);
+        }
+        return withOoxmlSourceType(withStatus);
     };
     const finalizeUnchanged = () => {
         if (normalizedExistingRevisions && keepNormalizedNoOp) {
@@ -181,9 +242,13 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
                     });
                 }
                 log('[OxmlEngine] Existing revisions from same author detected; rejecting previous changes to merge against baseline');
-                const rejected = rejectTrackedChangesInOoxml(inputOoxml, { author });
-                if (rejected.status === 'error') return finalize(rejected);
-                workingOoxml = rejected.oxml;
+                const soleParagraph = inputParagraphs.length === 1 ? inputParagraphs[0] : null;
+                preservedInsertedParagraphMark = insertedParagraphMarkMetadata(soleParagraph, author);
+                const rejected = rejectTrackedChangesInOoxml(inputOoxml, { author });
+                if (rejected.status === 'error') return finalize(rejected);
+                workingOoxml = preservedInsertedParagraphMark && !String(rejected.oxml || '').trim()
+                    ? emptyParagraphBaseline(soleParagraph, serializer)
+                    : rejected.oxml;
                 normalizedExistingRevisions = true;
                 const rejectedParsed = parseOoxmlSafe(workingOoxml, 'text/xml');
                 parseWarnings.push(...rejectedParsed.warnings);
@@ -230,8 +295,10 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
                     hasChanges: false,
                     status: 'error',
                     error: {
-                        code: 'EXISTING_REVISIONS',
-                        message: `Input OOXML contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Pass existingRevisions: "accept-all-first" or resolve revisions first.`
+                        code: 'EXISTING_REVISIONS',
+                        message: `Input OOXML contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Use existingRevisions: "slice-cross-author" for a surgical edit that preserves reviewer history; accepting or rejecting revisions requires separate authorization.`,
+                        revisionAuthors: authors,
+                        currentPolicy: existingRevisionsPolicy
                     }
                 });
             } else {

package/engine/run-builders.js

@@ -9,6 +9,7 @@ import { extractFormatFromRPr, RPR_SCHEMA_ORDER } from './rpr-helpers.js';
 import { createRevisionMetadata } from '../core/types.js';
 import { getFirstElementByTag } from '../core/xml-query.js';
 import { createWordElement } from '../core/word-xml.js';
+import { clonePropertiesWithoutRevisionHistory } from '../core/revision-cloning.js';
 
 /**
  * Creates an insertion/deletion wrapper.
@@ -319,14 +320,9 @@ export function snapshotAndAttachRPrChange(xmlDoc, rPr, author, dateStr, sourceN
     rPrChange.setAttribute('w:author', metadata.author);
     rPrChange.setAttribute('w:date', dateStr || metadata.date);
 
-    const previousRPr = createWordElement(xmlDoc, 'w:rPr');
     const source = sourceNode || rPr;
-
-    Array.from(source.childNodes).forEach(child => {
-        if (child.nodeName !== 'w:rPrChange') {
-            previousRPr.appendChild(child.cloneNode(true));
-        }
-    });
+    const previousRPr = clonePropertiesWithoutRevisionHistory(source)
+        || createWordElement(xmlDoc, 'w:rPr');
 
     rPrChange.appendChild(previousRPr);
 
@@ -369,14 +365,9 @@ export function snapshotAndAttachPPrChange(xmlDoc, pPr, author, dateStr, sourceN
     pPrChange.setAttribute('w:author', metadata.author);
     pPrChange.setAttribute('w:date', dateStr || metadata.date);
 
-    const previousPPr = createWordElement(xmlDoc, 'w:pPr');
     const source = sourceNode || pPr;
-
-    Array.from(source.childNodes).forEach(child => {
-        if (child.nodeType === 1 && child.nodeName !== 'w:pPrChange' && child.localName !== 'pPrChange') {
-            previousPPr.appendChild(child.cloneNode(true));
-        }
-    });
+    const previousPPr = clonePropertiesWithoutRevisionHistory(source)
+        || createWordElement(xmlDoc, 'w:pPr');
 
     pPrChange.appendChild(previousPPr);
 
@@ -390,4 +381,3 @@ export function snapshotAndAttachPPrChange(xmlDoc, pPr, author, dateStr, sourceN
     pPr.appendChild(pPrChange);
     return pPrChange;
 }
-

package/index.d.ts

@@ -1,5 +1,5 @@
 export type OoxmlSourceType = 'package' | 'document' | 'fragment';
-export type RedlineStatus = 'ok' | 'no-op' | 'error';
+export type RedlineStatus = 'ok' | 'no-op' | 'partial' | 'error';
 export type ExistingRevisionsPolicy = 'merge-same-author' | 'slice-cross-author' | 'reject-input' | 'accept-all-first' | 'accept-all-first-keep-normalized';
 export type RevisionView = 'accepted' | 'rejected';
 
@@ -68,6 +68,22 @@ export interface RedlineError {
   actual?: unknown;
   commentIds?: string[];
   comments?: Array<{ id: string; author: string; text: string }>;
+  recoveryVersion?: number;
+  category?: 'request_fixable' | 'target_refresh_required' | 'candidate_selection_required' | 'policy_choice_required' | 'user_authorization_required' | 'source_conflict' | 'library_or_builder_failure' | 'manual_document_resolution' | string;
+  context?: Record<string, unknown>;
+  recovery?: {
+    action: string;
+    sameArgumentsSafe: boolean;
+    requiresReinspection: boolean;
+    requiresUserAuthorization: boolean;
+    field?: string;
+    recommendedValue?: unknown;
+  };
+  expectedRevision?: RevisionToken;
+  currentRevision?: RevisionToken;
+  issueSummary?: { total: number; byCode: Array<{ code: string; count: number }> };
+  candidates?: unknown[];
+  [key: string]: unknown;
 }
 
 export interface RedlineOptions {

package/node/cli.js

@@ -6,29 +6,35 @@ import { validateDocxPackage } from '../services/standalone-docx-plumbing.js';
 import { validateRedlineOoxml } from '../core/redline-validation.js';
 import { configureLogger } from '../adapters/logger.js';
 import { isExistingRevisionsPolicy } from '../services/document-operation-contract.js';
+import { normalizeErrorWithRecovery } from '../services/error-recovery.js';
 
 const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
-const CLI_CONTRACT_VERSION = 3;
+const CLI_CONTRACT_VERSION = 5;
 const CLI_CAPABILITIES = [
     'atomic-batch-results-on-package-failure',
     'baseline-aware-validation',
     'compact-mutation-results',
     'cross-author-revision-slicing',
-    'document-scoped-list-revision-ids'
+    'document-scoped-list-revision-ids',
+    'batch-start-source-binding',
+    'recovery-envelope-v1',
+    'require-complete-exit',
+    'operations-stdin',
+    'agent-profile-v1'
 ];
 const commandOptions = {
     version: new Set(['help']),
     inspect: new Set(['help', 'search', 'revised', 'table', 'body', 'nonEmpty', 'index', 'indexes', 'range', 'view']),
     extract: new Set(['help', 'search', 'revised', 'table', 'body', 'nonEmpty', 'index', 'indexes', 'range', 'view']),
     preflight: new Set(['help', 'operations', 'author', 'strictTargets', 'target', 'modified', 'comment', 'textToComment', 'targetRef', 'existingRevisions']),
-    apply: new Set(['help', 'operations', 'author', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber', 'expectedRevision', 'target', 'modified', 'comment', 'textToComment', 'targetRef', 'existingRevisions', 'atomic', 'generateRedlines', 'noRedlines']),
+    apply: new Set(['help', 'operations', 'author', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber', 'expectedRevision', 'target', 'modified', 'comment', 'textToComment', 'targetRef', 'existingRevisions', 'atomic', 'generateRedlines', 'noRedlines', 'requireComplete', 'profile']),
     accept: new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
     reject: new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
     'delete-comments': new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
     validate: new Set(['help', 'baseline'])
 };
 
-function cliError(code, message, exitCode = 2, details) { return { status: 'error', error: { code, message, ...(details ? { details } : {}) }, exitCode }; }
+function cliError(code, message, exitCode = 2, details) { return { status: 'error', error: normalizeErrorWithRecovery({ code, message, ...(details ? { details } : {}) }), exitCode }; }
 const optionAliases = new Map([
     ['operationsFile', 'operations'],
     ['o', 'output'],
@@ -39,7 +45,8 @@ const optionAliases = new Map([
     ['no-overwrite', 'noOverwrite'],
     ['no-clobber', 'noClobber'],
     ['no-redlines', 'noRedlines'],
-    ['generate-redlines', 'generateRedlines']
+    ['generate-redlines', 'generateRedlines'],
+    ['require-complete', 'requireComplete']
 ]);
 function parseArgs(argv) {
     const positionals = []; const flags = {};
@@ -51,7 +58,7 @@ function parseArgs(argv) {
         const normalizedKey = rawKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
         const key = optionAliases.get(normalizedKey) || normalizedKey;
         if (inline !== undefined) flags[key] = inline;
-        else if (argv[index + 1] && (!argv[index + 1].startsWith('-') || /^-\d/.test(argv[index + 1]))) flags[key] = argv[++index];
+        else if (argv[index + 1] && (argv[index + 1] === '-' || !argv[index + 1].startsWith('-') || /^-\d/.test(argv[index + 1]))) flags[key] = argv[++index];
         else flags[key] = true;
     }
     return { command: positionals[0], input: positionals[1], extraPositionals: positionals.slice(2), flags };
@@ -113,7 +120,16 @@ function inspectionOptions(flags) {
     }
     return options;
 }
-async function readOperations(file, flags = {}) {
+async function readUtf8Stream(stream) {
+    if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') {
+        throw new Error('No readable stdin stream was provided.');
+    }
+    const chunks = [];
+    for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    return Buffer.concat(chunks).toString('utf8');
+}
+
+async function readOperations(file, flags = {}, stdin = process.stdin) {
     if (!file && flags?.target) {
         let op;
         if (flags.comment) {
@@ -138,7 +154,14 @@ async function readOperations(file, flags = {}) {
         return { operations: [op], expectedRevision: null };
     }
     if (!file) throw Object.assign(new Error('Use --operations <file.json> or --target <text>.'), { code: 'OPERATIONS_REQUIRED' });
-    let parsed; try { parsed = JSON.parse(await readFile(file, 'utf8')); } catch (error) { throw Object.assign(new Error(`Could not read operations JSON: ${error.message}`), { code: 'INVALID_OPERATIONS_FILE' }); }
+    let parsed;
+    try {
+        const source = file === '-' ? await readUtf8Stream(stdin) : await readFile(file, 'utf8');
+        parsed = JSON.parse(source);
+    } catch (error) {
+        const location = file === '-' ? ' from stdin' : '';
+        throw Object.assign(new Error(`Could not read operations JSON${location}: ${error.message}`), { code: 'INVALID_OPERATIONS_FILE' });
+    }
     const operations = Array.isArray(parsed) ? parsed : (parsed?.operations || parsed?.changes);
     if (!Array.isArray(operations)) throw Object.assign(new Error('Operations JSON must be an array or an object with an operations or changes array.'), { code: 'INVALID_OPERATIONS_FILE' });
     return { operations, expectedRevision: parsed?.expectedRevision || null };
@@ -177,7 +200,9 @@ function compactError(error) {
     if (!error || typeof error !== 'object') return error;
     const fields = [
         'code', 'stage', 'mismatchOffset', 'expectedExcerpt', 'actualExcerpt',
-        'expectedCodePoint', 'actualCodePoint', 'ownerAuthor', 'commentIds'
+        'expectedCodePoint', 'actualCodePoint', 'ownerAuthor', 'commentIds',
+        'recoveryVersion', 'category', 'field', 'captureRef', 'operationIndexes',
+        'consumedByOperation', 'expectedScope', 'actualScope'
     ];
     const compact = {};
     for (const field of fields) {
@@ -191,7 +216,37 @@ function compactError(error) {
         }));
     }
     if (Array.isArray(error.candidates)) {
-        compact.candidates = error.candidates.map(compactResolvedTarget);
+        compact.candidates = error.candidates.map(candidate => {
+            if (!candidate || typeof candidate !== 'object') return candidate;
+            const excerpt = boundedText(candidate.excerpt ?? candidate.exactText ?? candidate.text ?? '', 240);
+            return { ...compactResolvedTarget(candidate), ...(excerpt ? { excerpt } : {}) };
+        });
+    }
+    for (const field of ['recovery', 'issueSummary', 'expectedRevision', 'currentRevision']) {
+        if (error[field] !== undefined) compact[field] = error[field];
+    }
+    if (error.context && typeof error.context === 'object') {
+        compact.context = {
+            ...error.context,
+            ...(error.context.currentTarget ? {
+                currentTarget: {
+                    ...compactResolvedTarget(error.context.currentTarget),
+                    excerpt: boundedText(
+                        error.context.currentTarget.excerpt
+                            ?? error.context.currentTarget.exactText
+                            ?? error.context.currentTarget.text
+                            ?? '',
+                        240
+                    )
+                }
+            } : {})
+        };
+    }
+    if (error.sourceTarget && typeof error.sourceTarget === 'object') {
+        compact.sourceTarget = {
+            ...compactResolvedTarget(error.sourceTarget),
+            excerpt: boundedText(error.sourceTarget.text ?? error.sourceTarget.exactText ?? '', 240)
+        };
     }
     compact.message = boundedText(error.message || String(error));
     return compact;
@@ -314,7 +369,7 @@ function subtractValidationIssues(issues, baselineIssues) {
     });
 }
 
-export async function executeCli(argv) {
+export async function executeCli(argv, io = process) {
     const { command, input: rawInput, extraPositionals, flags } = parseArgs(argv);
     if (command === 'help' || flags.help) return { status: 'ok', command: 'help', usage: 'docx-redline <version|inspect|extract|preflight|apply|accept|reject|delete-comments|validate> [file.docx] [options]' };
     if (!command) return cliError('COMMAND_REQUIRED', 'A command is required.');
@@ -336,6 +391,10 @@ export async function executeCli(argv) {
     if (flags.existingRevisions != null && !isExistingRevisionsPolicy(flags.existingRevisions)) {
         return cliError('INVALID_OPERATION', `Unsupported existing-revisions policy: "${String(flags.existingRevisions)}".`);
     }
+    const profile = flags.profile == null ? null : String(flags.profile);
+    if (profile && profile !== 'agent') {
+        return cliError('INVALID_PROFILE', `Unknown execution profile: "${profile}". Supported profiles: agent.`);
+    }
     let inspectOptions = null;
     if (command === 'inspect' || command === 'extract') {
         try { inspectOptions = inspectionOptions(flags); }
@@ -374,7 +433,9 @@ export async function executeCli(argv) {
             const hasErrors = issues.some(issue => issue.severity === 'error');
             return { status: hasErrors ? 'error' : 'ok', command, input, valid: !hasErrors, issues };
         }
-        const opsData = command === 'preflight' || command === 'apply' ? await readOperations(flags.operations, flags) : null;
+        const opsData = command === 'preflight' || command === 'apply'
+            ? await readOperations(flags.operations, flags, io.stdin || process.stdin)
+            : null;
         const operations = opsData?.operations || null;
         let expectedRevision = opsData?.expectedRevision || null;
         if (flags.expectedRevision) {
@@ -400,15 +461,31 @@ export async function executeCli(argv) {
             }),
             command,
             input
-        };
-        if (command === 'apply') {
-            const author = flags.author || process.env.DOCX_REDLINE_AUTHOR || 'AI Redliner';
-            const generateRedlines = flags.generateRedlines !== undefined
-                ? (flags.generateRedlines !== 'false' && flags.generateRedlines !== false)
-                : (!flags.noRedlines);
-            const result = await document.applyOperations(operations, {
-                author,
-                atomic: flags.atomic === true || flags.atomic === 'true',
+        };
+        if (command === 'apply') {
+            const agentProfile = profile === 'agent';
+            const author = flags.author || process.env.DOCX_REDLINE_AUTHOR || 'AI Redliner';
+            const generateRedlines = flags.generateRedlines !== undefined
+                ? (flags.generateRedlines !== 'false' && flags.generateRedlines !== false)
+                : (!flags.noRedlines);
+            const atomic = flags.atomic !== undefined
+                ? (flags.atomic === true || flags.atomic === 'true')
+                : agentProfile;
+            const requireComplete = flags.requireComplete !== undefined
+                ? (flags.requireComplete === true || flags.requireComplete === 'true')
+                : agentProfile;
+            const effectiveOptions = {
+                author,
+                atomic,
+                strictTargets: true,
+                validate: true,
+                generateRedlines,
+                existingRevisions: flags.existingRevisions || 'merge-same-author',
+                requireComplete
+            };
+            const result = await document.applyOperations(operations, {
+                author,
+                atomic,
                 validate: true,
                 strictTargets: true,
                 generateRedlines,
@@ -420,7 +497,12 @@ export async function executeCli(argv) {
                 command,
                 input,
                 ...serializable(mutationResult),
-                ...(result.status === 'error' || result.error ? { exitCode: 2 } : {})
+                ...(profile ? { executionProfile: profile, effectiveOptions } : {}),
+                ...(result.status === 'error'
+                    ? { exitCode: 2 }
+                    : (result.status === 'partial' && requireComplete
+                        ? { exitCode: 3 }
+                        : {}))
             });
         }
         const filter = flags.allAuthors ? { allAuthors: true } : flags.author ? { author: String(flags.author) } : null;
@@ -430,8 +512,10 @@ export async function executeCli(argv) {
     } catch (error) { return cliError(error.code || 'CLI_FAILED', error.message); }
 }
 
-export async function runCli(argv = process.argv.slice(2), io = process) {
-    configureLogger({}, { level: 'silent' });
-    const result = await executeCli(argv); io.stdout.write(`${JSON.stringify(serializable(result), null, 2)}\n`);
-    return result.status === 'error' ? (result.exitCode || 1) : 0;
-}
+export async function runCli(argv = process.argv.slice(2), io = process) {
+    configureLogger({}, { level: 'silent' });
+    const result = await executeCli(argv, io); io.stdout.write(`${JSON.stringify(serializable(result), null, 2)}\n`);
+    return Number.isInteger(result.exitCode) && result.exitCode !== 0
+        ? result.exitCode
+        : (result.status === 'error' ? 1 : 0);
+}