greprag 5.64.0 → 5.65.0

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

@@ -0,0 +1,30 @@
+/** Pure managed-follower block helpers for canonical agent doctrine. */
+export interface DoctrineFollowerRender {
+    scopeKey: string;
+    harness: 'claude-code' | 'codex' | 'opencode';
+    revision: number;
+    body: string;
+}
+export type DoctrineFollowerOutcome = {
+    action: 'current';
+    content: string;
+    renderHash: string;
+} | {
+    action: 'seed' | 'update' | 'adopt';
+    content: string;
+    renderHash: string;
+} | {
+    action: 'diverged' | 'unmanaged';
+    content: string;
+    reason: string;
+    renderHash: string;
+};
+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?: {
+    force?: boolean;
+    adoptWholeFile?: boolean;
+}): DoctrineFollowerOutcome;

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

@@ -0,0 +1,104 @@
+"use strict";
+/** Pure managed-follower block helpers for canonical agent doctrine. */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doctrineRenderHash = doctrineRenderHash;
+exports.renderDoctrineFollowerBlock = renderDoctrineFollowerBlock;
+exports.patchDoctrineFollower = patchDoctrineFollower;
+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');
+}
+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 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;
+}
+/** 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 };
+        }
+        return {
+            action: 'unmanaged',
+            content: source,
+            renderHash,
+            reason: 'file has unmanaged content; explicitly adopt it or use --force',
+        };
+    }
+    const actualHash = doctrineRenderHash(existing.inner);
+    if (!options.force && actualHash !== existing.declaredHash) {
+        return {
+            action: 'diverged',
+            content: source,
+            renderHash,
+            reason: 'managed follower was edited after its last canonical render',
+        };
+    }
+    if (existing.revision === render.revision
+        && actualHash === renderHash
+        && existing.declaredHash === renderHash) {
+        return { action: 'current', content: source, renderHash };
+    }
+    return {
+        action: 'update',
+        content: source.replace(existing.whole, block),
+        renderHash,
+    };
+}
+//# sourceMappingURL=agent-doctrine-file.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,15 @@
+/** `greprag agents` — canonical agent-doctrine adoption and materialization. */
+type Harness = 'claude-code' | 'codex' | 'opencode';
+type Scope = 'global' | 'repo';
+export interface AgentDoctrineBootstrapResult {
+    canonicalScopes: Scope[];
+    currentFollowers: number;
+    changedFollowers: number;
+    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`. */
+export declare function bootstrapAgentDoctrine(apiKey: string, harness: Harness): Promise<AgentDoctrineBootstrapResult>;
+export declare function runAgents(args: string[]): Promise<void>;
+export {};

package/dist/commands/agents.js

@@ -0,0 +1,370 @@
+"use strict";
+/** `greprag agents` — canonical agent-doctrine adoption and materialization. */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bootstrapAgentDoctrine = bootstrapAgentDoctrine;
+exports.runAgents = runAgents;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const project_anchor_1 = require("../project-anchor");
+const proc_1 = require("../proc");
+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]
+  greprag agents optimize [--from <file>] [--scope global|repo] [--harness <name>]
+  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, then sync.`;
+function config(apiKeyOverride) {
+    return {
+        apiUrl: process.env.GREPRAG_API_URL || 'https://api.greprag.com',
+        apiKey: apiKeyOverride || process.env.GREPRAG_API_KEY || '',
+    };
+}
+function flag(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function repoRoot(cwd = process.cwd()) {
+    try {
+        return String((0, proc_1.safeExecSync)('git rev-parse --show-toplevel', {
+            cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        })).trim();
+    }
+    catch {
+        return path.resolve(cwd);
+    }
+}
+function relativeDirectory(root, requested) {
+    const absolute = requested
+        ? path.resolve(root, requested)
+        : path.resolve(process.cwd());
+    const relative = path.relative(root, absolute).replace(/\\/g, '/') || '.';
+    if (relative === '..' || relative.startsWith('../')) {
+        throw new Error('doctrine directory must be inside the current repo');
+    }
+    return relative;
+}
+function globalTargets() {
+    const home = os.homedir();
+    return [
+        {
+            harness: 'claude-code',
+            actualPath: path.join(home, '.claude', 'CLAUDE.md'),
+            manifestPath: '~/.claude/CLAUDE.md',
+        },
+        {
+            harness: 'codex',
+            actualPath: path.join(home, '.codex', 'AGENTS.md'),
+            manifestPath: '~/.codex/AGENTS.md',
+        },
+        {
+            harness: 'opencode',
+            actualPath: path.join(home, '.config', 'opencode', 'AGENTS.md'),
+            manifestPath: '~/.config/opencode/AGENTS.md',
+        },
+    ];
+}
+function repoTargets(root, directory) {
+    const base = directory === '.' ? root : path.join(root, ...directory.split('/'));
+    return [
+        {
+            harness: 'claude-code',
+            actualPath: path.join(base, 'CLAUDE.md'),
+            manifestPath: path.join(base, 'CLAUDE.md'),
+        },
+        {
+            harness: 'codex',
+            actualPath: path.join(base, 'AGENTS.md'),
+            manifestPath: path.join(base, 'AGENTS.md'),
+            note: 'shared AGENTS.md follower consumed by Codex and OpenCode',
+            combinedAgents: true,
+        },
+    ];
+}
+function parityUnitName(scope, projectId, directory) {
+    if (scope === 'global')
+        return 'agent-doctrine-global';
+    if (!projectId)
+        throw new Error('projectId required for repo doctrine');
+    const suffix = directory === '.'
+        ? 'root'
+        : 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 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));
+    }
+    else {
+        parts.push(renderSection(`${target.harness} Overlay`, doc.overlays[target.harness]));
+    }
+    return parts.filter(Boolean).join('\n\n').trim() + '\n';
+}
+async function apiJson(pathname, init, apiKeyOverride) {
+    const cfg = config(apiKeyOverride);
+    if (!cfg.apiKey)
+        throw new Error('GREPRAG_API_KEY not set — run `greprag init` first.');
+    const response = await fetch(`${cfg.apiUrl}${pathname}`, {
+        ...init,
+        headers: {
+            'Authorization': `Bearer ${cfg.apiKey}`,
+            ...(init?.body ? { 'Content-Type': 'application/json' } : {}),
+            ...(init?.headers || {}),
+        },
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok)
+        throw new Error(body.error || `HTTP ${response.status}`);
+    return body;
+}
+function context(scope, args) {
+    const root = repoRoot();
+    if (scope === 'global') {
+        return { projectId: null, directory: '.', root, targets: globalTargets() };
+    }
+    const anchor = (0, project_anchor_1.readAnchor)(root);
+    const directory = relativeDirectory(root, flag(args, '--directory'));
+    return {
+        projectId: anchor.projectId,
+        directory,
+        root,
+        targets: repoTargets(root, directory),
+    };
+}
+async function fetchDocument(scope, projectId, directory, apiKey) {
+    const params = new URLSearchParams({ scope, directory, harness: 'all' });
+    if (projectId)
+        params.set('projectId', projectId);
+    try {
+        const body = await apiJson(`/v1/agents?${params.toString()}`, undefined, apiKey);
+        return body.documents[0] || null;
+    }
+    catch (error) {
+        if (error instanceof Error && /not found/.test(error.message))
+            return null;
+        throw error;
+    }
+}
+function inferHarness(file, explicit) {
+    if (explicit === 'claude-code' || explicit === 'codex' || explicit === 'opencode')
+        return explicit;
+    return file && path.basename(file).toUpperCase() === 'CLAUDE.MD' ? 'claude-code' : 'codex';
+}
+function inferScope(file, explicit) {
+    if (explicit === 'global' || explicit === 'repo')
+        return explicit;
+    if (file) {
+        const absolute = path.resolve(file).toLowerCase();
+        if (globalTargets().some((target) => target.actualPath.toLowerCase() === absolute))
+            return 'global';
+    }
+    return 'repo';
+}
+async function reportSync(unitName, target, revision, renderHash, apiKey) {
+    await apiJson('/v1/agents/sync', {
+        method: 'POST',
+        body: JSON.stringify({
+            unitName,
+            harness: target.harness,
+            path: target.manifestPath,
+            revision,
+            renderHash,
+        }),
+    }, apiKey);
+}
+function targetMatchesHarness(target, harness) {
+    if (!harness || target.harness === harness)
+        return true;
+    return harness === 'opencode' && target.combinedAgents === true;
+}
+async function syncOne(params) {
+    const ctx = context(params.scope, params.args);
+    const doc = await fetchDocument(params.scope, ctx.projectId, ctx.directory, params.apiKey);
+    if (!doc) {
+        if (!params.quiet)
+            console.log(`${params.scope}: no canonical doctrine`);
+        return { canonical: false, current: 0, changed: 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 };
+    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, {
+            scopeKey: doc.scopeKey,
+            harness: target.harness,
+            revision: doc.revision,
+            body: renderForTarget(doc, target),
+        }, { force: params.force, adoptWholeFile: adopting });
+        const current = outcome.action === 'current';
+        if (current)
+            stats.current++;
+        else
+            stats.drift++;
+        const detail = 'reason' in outcome ? ` — ${outcome.reason}` : '';
+        if (!params.quiet) {
+            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) {
+            stats.blocked++;
+            continue;
+        }
+        if (params.check || current)
+            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);
+        stats.changed++;
+    }
+    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))
+        throw new Error(`source file not found: ${sourcePath}`);
+    const scope = inferScope(sourcePath, flag(args, '--scope'));
+    let 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'}`, {
+        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,
+            followers: ctx.targets.map((target) => ({
+                harness: target.harness,
+                path: target.manifestPath,
+                note: target.note,
+            })),
+        }),
+    });
+    console.log(`${adopt ? 'Adopted' : 'Optimized'} ${body.document.scopeKey} revision ${body.document.revision}.`);
+    if (!args.includes('--no-sync')) {
+        await syncOne({
+            scope,
+            args,
+            check: false,
+            force: args.includes('--force'),
+            adoptSourcePath: adopt ? sourcePath : undefined,
+        });
+    }
+}
+async function syncCommand(args, checkOverride = false) {
+    const requested = flag(args, '--scope') || 'all';
+    if (!['global', 'repo', 'all'].includes(requested)) {
+        throw new Error('--scope must be global|repo|all');
+    }
+    const scopes = requested === 'all' ? ['global', 'repo'] : [requested];
+    const check = checkOverride || args.includes('--check');
+    let drift = 0;
+    for (const scope of scopes) {
+        console.log(`${scope}:`);
+        const stats = await syncOne({ scope, args, check, force: args.includes('--force') });
+        drift += stats.drift;
+    }
+    if (check && drift > 0) {
+        console.error(`${drift} follower(s) need sync or reconciliation.`);
+        process.exitCode = 1;
+    }
+    else if (check) {
+        console.log('All materialized followers are current.');
+    }
+}
+/** 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`. */
+async function bootstrapAgentDoctrine(apiKey, harness) {
+    const result = {
+        canonicalScopes: [], currentFollowers: 0, changedFollowers: 0, blockedFollowers: 0,
+    };
+    for (const scope of ['global', 'repo']) {
+        const stats = await syncOne({
+            scope, args: [], check: false, force: false, apiKey, harness, quiet: true, seedOnly: true,
+        });
+        if (stats.canonical)
+            result.canonicalScopes.push(scope);
+        result.currentFollowers += stats.current;
+        result.changedFollowers += stats.changed;
+        result.blockedFollowers += stats.blocked;
+    }
+    return result;
+}
+async function runAgents(args) {
+    const sub = args[0];
+    if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
+        console.log(HELP);
+        return;
+    }
+    if (sub === 'adopt')
+        return writeCommand(args.slice(1), true);
+    if (sub === 'optimize')
+        return writeCommand(args.slice(1), false);
+    if (sub === 'sync')
+        return syncCommand(args.slice(1));
+    if (sub === 'status')
+        return syncCommand(args.slice(1), true);
+    throw new Error(`unknown agents command: ${sub}`);
+}
+//# sourceMappingURL=agents.js.map

package/dist/commands/agents.js.map

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

package/dist/commands/codex-chip/native.d.ts

@@ -28,6 +28,11 @@ export interface NativeChipHandoff {
         retryDelayMs: 750;
         settleBeforeRename?: true;
     };
+    createRecovery?: {
+        failureClass: string;
+        beforeRetry: readonly string[];
+        recoveredClientThreadId: string;
+    };
     dispatchSequence: readonly string[];
     verifyTitleCommand?: string;
     attachCommand?: string;

package/dist/commands/codex-chip/native.js

@@ -61,6 +61,18 @@ function expectedNativeTitle(manifest) {
 function fallbackNativeModel() {
     return (0, codex_model_policy_1.resolveChipModelSlot)('worker').model;
 }
+function ambiguousCreateRecovery(title, chipId) {
+    return {
+        failureClass: 'generic or transport create_thread failure after a visible task may have been created',
+        recoveredClientThreadId: 'recovered-create-thread:<threadId>',
+        beforeRetry: [
+            `Treat the failure as ambiguous success. Do not call create_thread again until recovery checks prove no existing ${title} task exists.`,
+            `Run list_threads with query ${JSON.stringify(title)} or ${chipId.slice(0, 8)}, then read_thread each candidate.`,
+            `Recover only if exactly one candidate contains durable manifest ${chipId} or the exact expected title; then continue title verification on that thread.`,
+            'For recovered tasks where no clientThreadId was returned, pass --client-thread recovered-create-thread:<threadId> to verifyTitleCommand.',
+        ],
+    };
+}
 /** Parent-side Desktop adapter primitive. Set early, then correct the observed
  * auto-title race with two consecutive read-backs. */
 async function verifyDesktopTitle(expected, surface, maxAttempts = 3) {
@@ -126,6 +138,7 @@ function nativeHandoff(manifest) {
             model: manifest.codex.model || fallbackNativeModel(),
             thinking: (0, selection_1.resolveDesktopThinking)(manifest.codex.effort),
         },
+        createRecovery: ambiguousCreateRecovery(title, manifest.id),
         titleVerification: {
             maxAttempts: 3, exactTitle: title, consecutiveReadBacks: 2, retryDelayMs: 750,
         },
@@ -142,6 +155,7 @@ function nativeHandoff(manifest) {
             'Rerun this handoff after attach only to inspect state; never replay the mission.',
         ] : [
             'Call create_thread with createRequest exactly. It contains the real mission, model, thinking, and native worktree; this is the only mission turn.',
+            'If create_thread returns a generic/transport failure, treat it as ambiguous success: run createRecovery.beforeRetry and recover a matching visible task before any retry.',
             'The UserPromptSubmit chip hook provisionally binds the task/cwd before tool use while setup continues.',
             'Resolve threadId and native cwd immediately. Call set_thread_title as soon as the thread appears, then read it back twice; retry only if auto-title overwrites it.',
             'Only after read_thread returns the exact title, run verifyTitleCommand. Fail loudly if the title is not durable.',
@@ -232,13 +246,21 @@ function verifyNativeBinding(manifest, params) {
     const idPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
     const clientMatch = /^(?:client-new-thread:)?([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i
         .exec(params.clientThreadId);
-    if (!clientMatch || !idPattern.test(params.threadId)) {
-        throw new Error('Attach requires the Codex-issued clientThreadId token and resolved threadId UUID.');
+    const recoveredClientMatch = /^recovered-create-thread:([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i
+        .exec(params.clientThreadId);
+    const clientToken = clientMatch?.[1] || recoveredClientMatch?.[1];
+    if (!clientToken || !idPattern.test(params.threadId)) {
+        throw new Error('Attach requires the Codex-issued clientThreadId token, or recovered-create-thread:<threadId>, and resolved threadId UUID.');
     }
-    if (clientMatch[1].toLowerCase() === params.threadId.toLowerCase() ||
-        params.threadId.toLowerCase() === manifest.parent.sessionId?.toLowerCase()) {
+    if (params.threadId.toLowerCase() === manifest.parent.sessionId?.toLowerCase()) {
         throw new Error('Native binding must identify a distinct resolved child task.');
     }
+    if (recoveredClientMatch && clientToken.toLowerCase() !== params.threadId.toLowerCase()) {
+        throw new Error('Recovered create_thread binding must name the same resolved child task as --thread.');
+    }
+    if (!recoveredClientMatch && clientToken.toLowerCase() === params.threadId.toLowerCase()) {
+        throw new Error('Native binding must identify a distinct client token and resolved child task.');
+    }
     const expectedTitle = expectedNativeTitle(manifest);
     if (params.title !== expectedTitle)
         throw new Error(`Native title was not durably verified as ${expectedTitle}.`);
@@ -251,6 +273,9 @@ function verifyNativeBinding(manifest, params) {
         !manifest.codex.threadId || !manifest.codex.nativeCwd)) {
         throw new Error('Native v4 title verification requires the initial mission hook to provisionally bind the task first.');
     }
+    if (recoveredClientMatch && manifest.version < 2) {
+        throw new Error('Recovered create_thread binding is only supported for native v4 mission tasks.');
+    }
     if (params.projectId !== manifest.codex.projectId || params.baseSha !== manifest.parent.baseSha) {
         throw new Error('Native project/base attestation does not match the prepared task.');
     }