greprag 5.65.1 → 5.65.3

package/dist/codex-chip-hooks.js

@@ -66,8 +66,8 @@ function context(input) {
         // adr: adr/codex-landing-doctrine.md — default parent-owned landing + the one FIX exception.
         'Landing: the parent owns merge, archive, and cleanup — do not merge, push, deploy, clean up, or edit the parent checkout. ONE exception: a mission whose first line begins `FIX:` (emitted by `greprag fix spawn`) carries its own Phase 3 landing contract — after peer conferral it merges its branch to main itself; cleanup stays native (`Clearance: safe to archive`), and push/release stays operator-gated.',
     ];
-    if (chip.codex.role === 'mechanic') {
-        lines.push('Harness: Codex. Role: visible native MECHANIC chip with ordinary writable authority, not an internal subagent.', 'Scope: repair GrepRAG-owned harness surfaces in this checkout: load entries, skill templates, docs, hook context, CLI messages, and tests. Codex owns native task creation, worktrees, permissions, Git, and task lifecycle.', 'Own diagnosis, implementation, tests, commit, and parent report. Inspect Codex behavior only far enough to correct GrepRAG guidance or report a precise external blocker.', 'Mechanic peer handoff: if a Mechanic peer offers to coordinate, integrate, rework, or take over a harness repair, hand off branch/commit, dirty files, checks, blockers, and caveats. Do not defend patch ownership; peers may take ownership within their assigned GrepRAG harness scope.', 'Visible delegation route: load `codex-chip-spawn` and create the child with `codex_app__create_thread` using the current project worktree target; load `chip-leader` for multi-chip seams. Never use `multi_agent_v1__spawn_agent` for a visible chip.');
+    if ((0, model_1.chipMissionKind)(chip) === 'fix') {
+        lines.push('Harness: Codex. Mission: visible native FIX chip with ordinary writable authority, not an internal subagent.', 'Scope: repair GrepRAG-owned harness surfaces in this checkout: load entries, skill templates, docs, hook context, CLI messages, and tests. Codex owns native task creation, worktrees, permissions, Git, and task lifecycle.', 'Own diagnosis, implementation, tests, commit, and parent report. Inspect Codex behavior only far enough to correct GrepRAG guidance or report a precise external blocker.', 'FIX peer handoff: if a peer offers to coordinate, integrate, rework, or take over a harness repair, hand off branch/commit, dirty files, checks, blockers, and caveats. Do not defend patch ownership; peers may take ownership within their assigned GrepRAG harness scope.', 'Visible delegation route: load `codex-chip-spawn` and create the child with `codex_app__create_thread` using the current project worktree target; load `chip-leader` for multi-chip seams. Never use `multi_agent_v1__spawn_agent` for a visible chip.');
     }
     return output(input.hook_event_name || 'SessionStart', lines.join('\n'));
 }

package/dist/codex-chip-hooks.js.map

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

package/dist/commands/agent-doctrine-file.d.ts

@@ -1,30 +1,48 @@
-/** Pure managed-follower block helpers for canonical agent doctrine. */
+/** Pure full-file follower helpers for canonical agent doctrine.
+ *
+ * Follower files must stay byte-faithful instruction files. Ownership state
+ * lives outside the markdown in the GrepRAG parity manifest.
+ */
 export interface DoctrineFollowerRender {
     scopeKey: string;
     harness: 'claude-code' | 'codex' | 'opencode';
     revision: number;
     body: string;
 }
+export interface DoctrineFollowerBaseline {
+    syncedRevision?: number | null;
+    syncedHash?: string | null;
+    syncedAt?: string | null;
+    dirtyAt?: string | null;
+}
 export type DoctrineFollowerOutcome = {
     action: 'current';
     content: string;
     renderHash: string;
+    shouldReportSync: boolean;
 } | {
-    action: 'seed' | 'update' | 'adopt';
+    action: 'seed' | 'update' | 'force';
     content: string;
     renderHash: string;
+    shouldReportSync: true;
 } | {
-    action: 'diverged' | 'unmanaged';
+    action: 'local-change' | 'conflict' | 'unmanaged';
     content: string;
     reason: string;
     renderHash: string;
+    shouldReportSync: false;
 };
 export declare function doctrineRenderHash(value: string): string;
-export declare function renderDoctrineFollowerBlock(render: DoctrineFollowerRender): string;
-/** Patch a generated follower without clobbering unadopted or hand-edited text.
- * A prior generated block is replaceable only while its actual body still
- * matches the hash declared in its own header. */
-export declare function patchDoctrineFollower(source: string, render: DoctrineFollowerRender, options?: {
+/** Return only the canonical body from an old marker-managed follower. */
+export declare function extractDoctrineFollowerBody(source: string): string | null;
+export declare function renderDoctrineFollower(render: DoctrineFollowerRender): string;
+/** Plan a full-file follower write.
+ *
+ * No marker comments are generated. A write is automatic only when the file is
+ * empty/missing, already exactly current, or still equals its last verified
+ * baseline. If both canon and disk changed since that baseline, the caller gets
+ * `conflict` and must not write.
+ */
+export declare function planDoctrineFollowerWrite(source: string, render: DoctrineFollowerRender, baseline: DoctrineFollowerBaseline | null | undefined, options?: {
     force?: boolean;
-    adoptWholeFile?: boolean;
 }): DoctrineFollowerOutcome;

package/dist/commands/agent-doctrine-file.js

@@ -1,5 +1,9 @@
 "use strict";
-/** Pure managed-follower block helpers for canonical agent doctrine. */
+/** Pure full-file follower helpers for canonical agent doctrine.
+ *
+ * Follower files must stay byte-faithful instruction files. Ownership state
+ * lives outside the markdown in the GrepRAG parity manifest.
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -35,70 +39,93 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.doctrineRenderHash = doctrineRenderHash;
-exports.renderDoctrineFollowerBlock = renderDoctrineFollowerBlock;
-exports.patchDoctrineFollower = patchDoctrineFollower;
+exports.extractDoctrineFollowerBody = extractDoctrineFollowerBody;
+exports.renderDoctrineFollower = renderDoctrineFollower;
+exports.planDoctrineFollowerWrite = planDoctrineFollowerWrite;
 const crypto = __importStar(require("node:crypto"));
-function normalizedBody(value) {
-    return value.replace(/\r\n/g, '\n').trim();
-}
 function doctrineRenderHash(value) {
-    return crypto.createHash('sha256').update(normalizedBody(value)).digest('hex');
+    return crypto.createHash('sha256').update(value).digest('hex');
+}
+const LEGACY_BLOCK_RE = /<!--\s*greprag:agents:start\s+scope=\S+\s+harness=\S+\s+revision=(\d+)\s+hash=([a-f0-9]{64})(?:\s+chars=(\d+))?\s*-->\r?\n([\s\S]*?)<!--\s*greprag:agents:end\s*-->/i;
+/** Return only the canonical body from an old marker-managed follower. */
+function extractDoctrineFollowerBody(source) {
+    const match = source.match(LEGACY_BLOCK_RE);
+    if (!match)
+        return null;
+    const chars = match[3] === undefined ? null : Number(match[3]);
+    const captured = match[4];
+    return chars === null ? captured.replace(/\r?\n$/, '') : captured.slice(0, chars);
+}
+function renderDoctrineFollower(render) {
+    return render.body;
 }
-function renderDoctrineFollowerBlock(render) {
-    const body = normalizedBody(render.body);
-    const hash = doctrineRenderHash(body);
-    return `<!-- greprag:agents:start scope=${render.scopeKey} harness=${render.harness} revision=${render.revision} hash=${hash} -->\n`
-        + `${body}\n<!-- greprag:agents:end -->`;
+function hasSyncedBaseline(baseline) {
+    return !!baseline?.syncedHash && /^[a-f0-9]{64}$/i.test(baseline.syncedHash);
 }
-function findBlock(source) {
-    const pattern = /<!--\s*greprag:agents:start\s+scope=\S+\s+harness=\S+\s+revision=(\d+)\s+hash=([a-f0-9]{64})\s*-->\r?\n?([\s\S]*?)\r?\n?<!--\s*greprag:agents:end\s*-->/i;
-    const match = source.match(pattern);
-    return match ? {
-        whole: match[0],
-        revision: Number(match[1]),
-        declaredHash: match[2].toLowerCase(),
-        inner: match[3],
-    } : null;
+function canonChangedSinceBaseline(baseline, render, renderHash) {
+    if (!hasSyncedBaseline(baseline))
+        return false;
+    return baseline.syncedRevision !== render.revision || baseline.syncedHash !== renderHash;
 }
-/** Patch a generated follower without clobbering unadopted or hand-edited text.
- * A prior generated block is replaceable only while its actual body still
- * matches the hash declared in its own header. */
-function patchDoctrineFollower(source, render, options = {}) {
-    const block = renderDoctrineFollowerBlock(render);
-    const renderHash = doctrineRenderHash(render.body);
-    const existing = findBlock(source);
-    if (!existing) {
-        if (!source.trim()) {
-            return { action: 'seed', content: block + '\n', renderHash };
-        }
-        if (options.force || options.adoptWholeFile) {
-            return { action: 'adopt', content: block + '\n', renderHash };
-        }
+/** Plan a full-file follower write.
+ *
+ * No marker comments are generated. A write is automatic only when the file is
+ * empty/missing, already exactly current, or still equals its last verified
+ * baseline. If both canon and disk changed since that baseline, the caller gets
+ * `conflict` and must not write.
+ */
+function planDoctrineFollowerWrite(source, render, baseline, options = {}) {
+    const body = renderDoctrineFollower(render);
+    const renderHash = doctrineRenderHash(body);
+    const sourceHash = doctrineRenderHash(source);
+    const baselineHash = baseline?.syncedHash?.toLowerCase() || null;
+    const synced = hasSyncedBaseline(baseline);
+    if (sourceHash === renderHash) {
         return {
-            action: 'unmanaged',
+            action: 'current',
             content: source,
             renderHash,
-            reason: 'file has unmanaged content; explicitly adopt it or use --force',
+            shouldReportSync: baseline?.syncedRevision !== render.revision || baselineHash !== renderHash,
         };
     }
-    const actualHash = doctrineRenderHash(existing.inner);
-    if (!options.force && actualHash !== existing.declaredHash) {
+    if (options.force) {
+        return { action: 'force', content: body, renderHash, shouldReportSync: true };
+    }
+    if (!source.trim()) {
+        return { action: 'seed', content: body, renderHash, shouldReportSync: true };
+    }
+    if (!synced) {
         return {
-            action: 'diverged',
+            action: 'unmanaged',
             content: source,
             renderHash,
-            reason: 'managed follower was edited after its last canonical render',
+            shouldReportSync: false,
+            reason: 'file has no external sync baseline; enroll only when bytes already match canon or use --force',
         };
     }
-    if (existing.revision === render.revision
-        && actualHash === renderHash
-        && existing.declaredHash === renderHash) {
-        return { action: 'current', content: source, renderHash };
+    const diskChanged = sourceHash !== baselineHash;
+    const canonChanged = canonChangedSinceBaseline(baseline, render, renderHash);
+    const dirty = !!baseline?.dirtyAt && (!baseline.syncedAt || baseline.dirtyAt > baseline.syncedAt);
+    if (!diskChanged && canonChanged) {
+        return { action: 'update', content: body, renderHash, shouldReportSync: true };
+    }
+    if (diskChanged && canonChanged) {
+        return {
+            action: 'conflict',
+            content: source,
+            renderHash,
+            shouldReportSync: false,
+            reason: 'both canon and follower changed since the last verified sync; pull or reconcile explicitly',
+        };
     }
     return {
-        action: 'update',
-        content: source.replace(existing.whole, block),
+        action: 'local-change',
+        content: source,
         renderHash,
+        shouldReportSync: false,
+        reason: dirty
+            ? 'follower has a worthy direct edit after sync; pull it to canon or revert it before push'
+            : 'follower changed since the last verified sync; pull it to canon or revert it before push',
     };
 }
 //# sourceMappingURL=agent-doctrine-file.js.map

package/dist/commands/agent-doctrine-file.js.map

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

package/dist/commands/agents.d.ts

@@ -8,8 +8,8 @@ export interface AgentDoctrineBootstrapResult {
     blockedFollowers: number;
 }
 /** Init-time seed for the active harness. No canon is a clean no-op; only a
- * missing/empty follower is written. Every existing file, including a stale
- * managed follower, requires an explicit `agents sync`. */
+ * missing/empty follower is written. Every existing nonmatching file requires
+ * an explicit `agents push` or `agents pull`. */
 export declare function bootstrapAgentDoctrine(apiKey: string, harness: Harness): Promise<AgentDoctrineBootstrapResult>;
 export declare function runAgents(args: string[]): Promise<void>;
 export {};

package/dist/commands/agents.js

@@ -46,16 +46,21 @@ const agent_doctrine_file_1 = require("./agent-doctrine-file");
 const HELP = `greprag agents — canonical CLAUDE.md / AGENTS.md doctrine
 
 USAGE
-  greprag agents adopt <file> [--scope global|repo] [--harness <name>] [--raw] [--no-sync]
-  greprag agents optimize [--from <file>] [--scope global|repo] [--harness <name>] [--no-sync]
+  greprag agents pull <file> [--scope global|repo] [--harness <name>] [--push]
+  greprag agents push [--scope global|repo|all] [--check] [--force]
+  greprag agents adopt <file> [--scope global|repo] [--harness <name>] [--no-sync]
+  greprag agents revise <file> [--scope global|repo] [--harness <name>] [--no-sync]
+  greprag agents overlay set <harness> <file> [--scope global|repo] [--no-sync]
+  greprag agents overlay derive <harness> <shared-file> <rendered-file> [--scope global|repo] [--no-sync]
+  greprag agents overlay clear <harness> [--scope global|repo] [--no-sync]
   greprag agents sync [--scope global|repo|all] [--check] [--force]
   greprag agents status [--scope global|repo|all]
 
 MODEL
-  Adoption is bidirectional once. After adoption, load://agents is canonical
-  and instruction files are generated followers. Direct follower edits become
-  drift candidates; use optimize --from, inspect with load agents, then sync.
-  --no-sync advances canon without writing followers; use it as the preview gate.`;
+  Adopt and revise copy source bytes exactly; no model rewrites doctrine.
+  Harness translations are raw additive suffixes. Pull writes disk to canon.
+  Push writes canon to disk only when the external sync baseline is clean.
+  Status/check never writes.`;
 function config(apiKeyOverride) {
     return {
         apiUrl: process.env.GREPRAG_API_URL || 'https://api.greprag.com',
@@ -133,19 +138,24 @@ function parityUnitName(scope, projectId, directory) {
         : crypto.createHash('sha256').update(directory).digest('hex').slice(0, 8);
     return `agent-doctrine-${projectId.slice(0, 8)}-${suffix}`;
 }
-function renderSection(title, value) {
-    return value.trim() ? `## ${title}\n\n${value.trim()}` : '';
+function uniqueNonempty(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        if (!value)
+            continue;
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        out.push(value);
+    }
+    return out;
 }
 function renderForTarget(doc, target) {
-    const parts = [doc.shared.trim()];
     if (target.combinedAgents) {
-        parts.push(renderSection('Codex Overlay', doc.overlays.codex));
-        parts.push(renderSection('OpenCode Overlay', doc.overlays.opencode));
+        return doc.shared + uniqueNonempty([doc.overlays.codex, doc.overlays.opencode]).join('');
     }
-    else {
-        parts.push(renderSection(`${target.harness} Overlay`, doc.overlays[target.harness]));
-    }
-    return parts.filter(Boolean).join('\n\n').trim() + '\n';
+    return doc.shared + (doc.overlays[target.harness] || '');
 }
 async function apiJson(pathname, init, apiKeyOverride) {
     const cfg = config(apiKeyOverride);
@@ -192,6 +202,27 @@ async function fetchDocument(scope, projectId, directory, apiKey) {
         throw error;
     }
 }
+async function fetchFollowerBaselines(unitName, apiKey) {
+    try {
+        const body = await apiJson('/v1/parity/list', undefined, apiKey);
+        const unit = body.units.find((candidate) => candidate.name === unitName);
+        const baselines = new Map();
+        for (const follower of unit?.followers || []) {
+            if (!follower.path)
+                continue;
+            baselines.set(`${follower.harness}\0${follower.path}`, {
+                syncedRevision: follower.syncedRevision,
+                syncedHash: follower.syncedHash,
+                syncedAt: follower.syncedAt,
+                dirtyAt: follower.dirtyAt,
+            });
+        }
+        return baselines;
+    }
+    catch {
+        return new Map();
+    }
+}
 function inferHarness(file, explicit) {
     if (explicit === 'claude-code' || explicit === 'codex' || explicit === 'opencode')
         return explicit;
@@ -230,22 +261,22 @@ async function syncOne(params) {
     if (!doc) {
         if (!params.quiet)
             console.log(`${params.scope}: no canonical doctrine`);
-        return { canonical: false, current: 0, changed: 0, blocked: 0, drift: 0 };
+        return { canonical: false, current: 0, changed: 0, enrolled: 0, blocked: 0, drift: 0 };
     }
     const unitName = parityUnitName(params.scope, ctx.projectId, ctx.directory);
-    const stats = { canonical: true, current: 0, changed: 0, blocked: 0, drift: 0 };
+    const baselines = await fetchFollowerBaselines(unitName, params.apiKey);
+    const stats = { canonical: true, current: 0, changed: 0, enrolled: 0, blocked: 0, drift: 0 };
     for (const target of ctx.targets.filter(t => targetMatchesHarness(t, params.harness))) {
         const source = fs.existsSync(target.actualPath)
             ? fs.readFileSync(target.actualPath, 'utf8')
             : '';
-        const adopting = !!params.adoptSourcePath
-            && path.resolve(params.adoptSourcePath).toLowerCase() === path.resolve(target.actualPath).toLowerCase();
-        const outcome = (0, agent_doctrine_file_1.patchDoctrineFollower)(source, {
+        const rendered = renderForTarget(doc, target);
+        const outcome = (0, agent_doctrine_file_1.planDoctrineFollowerWrite)(source, {
             scopeKey: doc.scopeKey,
             harness: target.harness,
             revision: doc.revision,
-            body: renderForTarget(doc, target),
-        }, { force: params.force, adoptWholeFile: adopting });
+            body: rendered,
+        }, baselines.get(`${target.harness}\0${target.manifestPath}`), { force: params.force });
         const current = outcome.action === 'current';
         if (current)
             stats.current++;
@@ -256,12 +287,20 @@ async function syncOne(params) {
             console.log(`  ${current ? 'fresh' : outcome.action.padEnd(9)} ${target.actualPath}${detail}`);
         }
         const seedOnlyBlocked = params.seedOnly && !current && outcome.action !== 'seed';
-        if (outcome.action === 'diverged' || outcome.action === 'unmanaged' || seedOnlyBlocked) {
+        if (outcome.action === 'conflict' || outcome.action === 'local-change'
+            || outcome.action === 'unmanaged' || seedOnlyBlocked) {
             stats.blocked++;
             continue;
         }
-        if (params.check || current)
+        if (params.check)
             continue;
+        if (current) {
+            if (outcome.shouldReportSync) {
+                await reportSync(unitName, target, doc.revision, outcome.renderHash, params.apiKey);
+                stats.enrolled++;
+            }
+            continue;
+        }
         fs.mkdirSync(path.dirname(target.actualPath), { recursive: true });
         fs.writeFileSync(target.actualPath, outcome.content, 'utf8');
         await reportSync(unitName, target, doc.revision, outcome.renderHash, params.apiKey);
@@ -269,31 +308,32 @@ async function syncOne(params) {
     }
     return stats;
 }
-async function writeCommand(args, adopt) {
-    const positional = adopt && args[0] && !args[0].startsWith('-') ? args[0] : undefined;
-    const from = flag(args, '--from') || positional;
-    if (adopt && !from)
-        throw new Error('adopt requires a source file');
-    const sourcePath = from ? path.resolve(from) : undefined;
-    if (sourcePath && !fs.existsSync(sourcePath))
+async function exactSourceCommand(args, mode) {
+    const from = args[0] && !args[0].startsWith('-') ? args[0] : undefined;
+    if (!from)
+        throw new Error(`${mode} requires a source file`);
+    const sourcePath = path.resolve(from);
+    if (!fs.existsSync(sourcePath))
         throw new Error(`source file not found: ${sourcePath}`);
     const scope = inferScope(sourcePath, flag(args, '--scope'));
-    let harness = inferHarness(sourcePath, flag(args, '--harness'));
+    const harness = inferHarness(sourcePath, flag(args, '--harness'));
     const ctx = context(scope, args);
-    const current = adopt ? null : await fetchDocument(scope, ctx.projectId, ctx.directory);
-    if (!sourcePath && current && !flag(args, '--harness'))
-        harness = current.sourceHarness;
-    const body = await apiJson(`/v1/agents/${adopt ? 'adopt' : 'optimize'}`, {
+    const current = mode === 'adopt' ? null : await fetchDocument(scope, ctx.projectId, ctx.directory);
+    const endpointMode = mode === 'pull'
+        ? current ? 'revise' : 'adopt'
+        : mode;
+    const fileContent = fs.readFileSync(sourcePath, 'utf8');
+    const content = (0, agent_doctrine_file_1.extractDoctrineFollowerBody)(fileContent) ?? fileContent;
+    const body = await apiJson(`/v1/agents/${endpointMode}`, {
         method: 'POST',
         body: JSON.stringify({
             scope,
             projectId: ctx.projectId,
             directory: ctx.directory,
             sourceHarness: harness,
-            sourcePath: sourcePath || null,
-            ...(sourcePath ? { content: fs.readFileSync(sourcePath, 'utf8') } : {}),
-            optimize: !args.includes('--raw'),
-            expectedRevision: current?.revision ?? null,
+            sourcePath,
+            content,
+            expectedRevision: endpointMode === 'revise' ? current?.revision ?? null : null,
             followers: ctx.targets.map((target) => ({
                 harness: target.harness,
                 path: target.manifestPath,
@@ -301,17 +341,87 @@ async function writeCommand(args, adopt) {
             })),
         }),
     });
-    console.log(`${adopt ? 'Adopted' : 'Optimized'} ${body.document.scopeKey} revision ${body.document.revision}.`);
-    if (!args.includes('--no-sync')) {
+    const verb = mode === 'pull' ? 'Pulled' : mode === 'adopt' ? 'Adopted' : 'Revised';
+    console.log(`${verb} ${body.document.scopeKey} revision ${body.document.revision}.`);
+    const shouldPush = mode === 'pull'
+        ? args.includes('--push')
+        : !args.includes('--no-sync');
+    if (shouldPush) {
         await syncOne({
             scope,
             args,
             check: false,
             force: args.includes('--force'),
-            adoptSourcePath: adopt ? sourcePath : undefined,
         });
     }
 }
+async function overlayCommand(args) {
+    const action = args[0];
+    const harnessRaw = args[1];
+    if (action !== 'set' && action !== 'clear' && action !== 'derive') {
+        throw new Error('overlay requires set, derive, or clear');
+    }
+    const harness = inferHarness(undefined, harnessRaw);
+    if (harnessRaw !== harness)
+        throw new Error('overlay harness must be claude-code, codex, or opencode');
+    const file = action === 'set' ? args[2] : undefined;
+    if (action === 'set' && !file)
+        throw new Error('overlay set requires a source file');
+    const sharedFile = action === 'derive' ? args[2] : undefined;
+    const renderedFile = action === 'derive' ? args[3] : undefined;
+    if (action === 'derive' && (!sharedFile || !renderedFile)) {
+        throw new Error('overlay derive requires <shared-file> <rendered-file>');
+    }
+    const sourcePath = file ? path.resolve(file) : null;
+    if (sourcePath && !fs.existsSync(sourcePath))
+        throw new Error(`source file not found: ${sourcePath}`);
+    const sharedPath = sharedFile ? path.resolve(sharedFile) : null;
+    const renderedPath = renderedFile ? path.resolve(renderedFile) : null;
+    if (sharedPath && !fs.existsSync(sharedPath))
+        throw new Error(`shared file not found: ${sharedPath}`);
+    if (renderedPath && !fs.existsSync(renderedPath))
+        throw new Error(`rendered file not found: ${renderedPath}`);
+    const scope = inferScope(undefined, flag(args, '--scope'));
+    const ctx = context(scope, args);
+    const current = await fetchDocument(scope, ctx.projectId, ctx.directory);
+    if (!current)
+        throw new Error('canonical doctrine does not exist; adopt it first');
+    let content = '';
+    if (sourcePath) {
+        content = fs.readFileSync(sourcePath, 'utf8');
+    }
+    else if (sharedPath && renderedPath) {
+        const shared = fs.readFileSync(sharedPath, 'utf8');
+        const rendered = fs.readFileSync(renderedPath, 'utf8');
+        if (!rendered.startsWith(shared)) {
+            throw new Error('rendered file does not start with shared file bytes; cannot derive exact suffix');
+        }
+        content = rendered.slice(shared.length);
+    }
+    const body = await apiJson('/v1/agents/overlay', {
+        method: 'POST',
+        body: JSON.stringify({
+            scope,
+            projectId: ctx.projectId,
+            directory: ctx.directory,
+            sourceHarness: harness,
+            sourcePath: renderedPath || sourcePath,
+            content,
+            overlayHarness: harness,
+            expectedRevision: current.revision,
+            followers: ctx.targets.map((target) => ({
+                harness: target.harness,
+                path: target.manifestPath,
+                note: target.note,
+            })),
+        }),
+    });
+    const verb = action === 'set' ? 'Set' : action === 'derive' ? 'Derived' : 'Cleared';
+    console.log(`${verb} ${harness} overlay at revision ${body.document.revision}.`);
+    if (!args.includes('--no-sync')) {
+        await syncOne({ scope, args, check: false, force: args.includes('--force') });
+    }
+}
 async function syncCommand(args, checkOverride = false) {
     const requested = flag(args, '--scope') || 'all';
     if (!['global', 'repo', 'all'].includes(requested)) {
@@ -334,8 +444,8 @@ async function syncCommand(args, checkOverride = false) {
     }
 }
 /** Init-time seed for the active harness. No canon is a clean no-op; only a
- * missing/empty follower is written. Every existing file, including a stale
- * managed follower, requires an explicit `agents sync`. */
+ * missing/empty follower is written. Every existing nonmatching file requires
+ * an explicit `agents push` or `agents pull`. */
 async function bootstrapAgentDoctrine(apiKey, harness) {
     const result = {
         canonicalScopes: [], currentFollowers: 0, changedFollowers: 0, blockedFollowers: 0,
@@ -358,10 +468,19 @@ async function runAgents(args) {
         console.log(HELP);
         return;
     }
+    if (sub === 'pull')
+        return exactSourceCommand(args.slice(1), 'pull');
+    if (sub === 'push')
+        return syncCommand(args.slice(1));
     if (sub === 'adopt')
-        return writeCommand(args.slice(1), true);
-    if (sub === 'optimize')
-        return writeCommand(args.slice(1), false);
+        return exactSourceCommand(args.slice(1), 'adopt');
+    if (sub === 'revise')
+        return exactSourceCommand(args.slice(1), 'revise');
+    if (sub === 'overlay')
+        return overlayCommand(args.slice(1));
+    if (sub === 'optimize') {
+        throw new Error('agents optimize was removed: use lossless agents pull or explicit agents overlay');
+    }
     if (sub === 'sync')
         return syncCommand(args.slice(1));
     if (sub === 'status')