@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/dist/lib/agent-clients/adapters/codex-lifecycle/sandbox-controller.js

@@ -0,0 +1,398 @@
+import crypto from 'node:crypto';
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import semver from 'semver';
+import * as toml from 'smol-toml';
+import { requestSandboxControl } from '../../../sandbox/control/client.js';
+import { readSandboxControlStatus } from '../../../sandbox/control/state.js';
+import { getProcessStartTime, isProcessAlive } from '../../../server/process-state.js';
+import { computeLifecycleBuildIdentity } from './build-identity.js';
+const CONTEXT_TTL_MS = 4 * 60 * 60 * 1_000;
+function digestFiles(files) {
+    const hash = crypto.createHash('sha256');
+    for (const file of [...files].sort()) {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error('CODEX_SANDBOX_CONTROLLER_BUNDLE_MISMATCH');
+        }
+        hash.update(path.basename(file));
+        hash.update('\0');
+        hash.update(fs.readFileSync(file));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+function copyRegular(source, destination, mode) {
+    const stat = fs.lstatSync(source);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_INPUT_INVALID');
+    }
+    fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+    fs.copyFileSync(source, destination);
+    fs.chmodSync(destination, mode);
+}
+function controlFromEnvironment() {
+    const token = process.env.AGENT_INFRA_CONTROL_TOKEN;
+    const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
+    const channelDir = process.env.AGENT_INFRA_CONTROL_DIR;
+    const statusDir = process.env.AGENT_INFRA_CONTROL_STATUS_DIR;
+    const runtimeDir = process.env.AGENT_INFRA_RUNTIME_DIR;
+    if (!token || !generation || !channelDir || !statusDir || !runtimeDir) {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_CONTROL_MISSING');
+    }
+    return { token, generation, channelDir, statusDir, runtimeDir };
+}
+function verifyRuntime(runtimeDir) {
+    let stat;
+    try {
+        stat = fs.lstatSync(runtimeDir);
+    }
+    catch {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_RUNTIME_UNAVAILABLE');
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_RUNTIME_UNAVAILABLE');
+    }
+    const probe = path.join(runtimeDir, `.controller-${process.pid}-${crypto.randomUUID()}.probe`);
+    try {
+        fs.writeFileSync(probe, 'runtime-probe\n', { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+        if (fs.readFileSync(probe, 'utf8') !== 'runtime-probe\n') {
+            throw new Error('probe mismatch');
+        }
+    }
+    catch {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_RUNTIME_UNAVAILABLE');
+    }
+    finally {
+        fs.rmSync(probe, { force: true });
+    }
+}
+function verifyControl(taskId, control) {
+    verifyRuntime(control.runtimeDir);
+    let status = null;
+    let lastError = null;
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+        try {
+            status = readSandboxControlStatus(control.statusDir);
+            break;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < 4)
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+        }
+    }
+    if (!status) {
+        throw new Error(`CODEX_SANDBOX_CONTROLLER_CONTROL_UNAVAILABLE: ${String(lastError)}`);
+    }
+    if (status.generation !== control.generation
+        || status.state !== 'healthy'
+        || Date.now() - status.updatedAt > 1_500) {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_CONTROL_UNAVAILABLE');
+    }
+    const response = requestSandboxControl({
+        family: 'task-orchestration',
+        args: [taskId, 'status'],
+        ...control,
+        timeoutMs: 30_000
+    });
+    let payload = {};
+    try {
+        payload = JSON.parse(response.stdout);
+    }
+    catch {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_TASK_BINDING_INVALID');
+    }
+    if (payload.taskId !== taskId)
+        throw new Error('CODEX_SANDBOX_CONTROLLER_TASK_BINDING_INVALID');
+}
+function detectedCodexVersion() {
+    const result = spawnSync('codex', ['--version'], { encoding: 'utf8' });
+    const version = /codex-cli\s+(\d+\.\d+\.\d+)/u.exec(result.stdout ?? '')?.[1];
+    if (result.status !== 0 || !version)
+        throw new Error('CODEX_SANDBOX_CONTROLLER_CODEX_UNAVAILABLE');
+    return version;
+}
+function sanitizedConfig(source, destination, sourceHome, targetHome) {
+    if (!fs.existsSync(source))
+        return [];
+    const parsed = toml.parse(fs.readFileSync(source, 'utf8'));
+    const allowed = new Set([
+        'model',
+        'model_provider',
+        'model_providers',
+        'model_reasoning_effort',
+        'model_auto_compact_token_limit',
+        'preferred_auth_method'
+    ]);
+    const output = Object.fromEntries(Object.entries(parsed).filter(([key]) => allowed.has(key)));
+    const catalog = parsed.model_catalog_json;
+    if (typeof catalog === 'string' && catalog.trim()) {
+        const resolved = path.resolve(sourceHome, catalog.replace(/^~[/\\]/u, ''));
+        const relative = path.relative(sourceHome, resolved);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            throw new Error('CODEX_SANDBOX_CONTROLLER_CONFIG_PATH_INVALID');
+        }
+        const target = path.join(targetHome, 'model-catalogs', path.basename(resolved));
+        copyRegular(resolved, target, 0o600);
+        output.model_catalog_json = target;
+    }
+    fs.writeFileSync(destination, `${toml.stringify(output)}\n`, { mode: 0o600 });
+    const providerEnvironment = new Set();
+    const providers = output.model_providers;
+    if (providers && typeof providers === 'object' && !Array.isArray(providers)) {
+        for (const provider of Object.values(providers)) {
+            if (!provider || typeof provider !== 'object' || Array.isArray(provider))
+                continue;
+            for (const key of ['env_key', 'envKey']) {
+                const name = provider[key];
+                if (typeof name === 'string' && /^[A-Z][A-Z0-9_]{1,127}$/u.test(name)) {
+                    providerEnvironment.add(name);
+                }
+            }
+        }
+    }
+    return Object.freeze([...providerEnvironment]);
+}
+function isolatedEnvironment(home, shimDir, contextPath, taskId, control, providerEnvironment, sourceEnvironment) {
+    const inherited = new Set([
+        'LANG', 'LC_ALL', 'TERM', 'COLORTERM',
+        'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY',
+        'http_proxy', 'https_proxy', 'no_proxy',
+        'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS',
+        'CODEX_CI',
+        ...providerEnvironment
+    ]);
+    const env = {};
+    for (const key of inherited) {
+        if (sourceEnvironment[key] !== undefined)
+            env[key] = sourceEnvironment[key];
+    }
+    return {
+        ...env,
+        HOME: home,
+        CODEX_HOME: home,
+        PATH: `${shimDir}${path.delimiter}${sourceEnvironment.PATH ?? ''}`,
+        AGENT_INFRA_TASK_ID: taskId,
+        AGENT_INFRA_CONTROL_TOKEN: control.token,
+        AGENT_INFRA_CONTROL_GENERATION: control.generation,
+        AGENT_INFRA_CONTROL_DIR: control.channelDir,
+        AGENT_INFRA_CONTROL_STATUS_DIR: control.statusDir,
+        AGENT_INFRA_RUNTIME_DIR: control.runtimeDir,
+        AGENT_INFRA_CODEX_CONTROLLER_CONTEXT: contextPath
+    };
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function prepareCodexSandboxController(input, options = {}) {
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const sourceHome = path.resolve(options.codexHome ?? process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex'));
+    const control = options.control ?? controlFromEnvironment();
+    (options.verifyTaskBinding ?? verifyControl)(input.taskId, control);
+    const version = (options.codexVersion ?? detectedCodexVersion)();
+    if (!semver.gte(version, '0.147.0'))
+        throw new Error('CODEX_SANDBOX_CONTROLLER_CODEX_UNSUPPORTED');
+    const runtimeRoot = path.resolve(options.temporaryRoot
+        ?? path.join(os.tmpdir(), 'agent-infra-codex-controllers'));
+    fs.mkdirSync(runtimeRoot, { recursive: true, mode: 0o700 });
+    fs.chmodSync(runtimeRoot, 0o700);
+    const key = crypto.createHash('sha256')
+        .update(`${input.taskId}\0${control.generation}`)
+        .digest('hex');
+    const leasePath = path.join(runtimeRoot, `${key}.lease.json`);
+    if (fs.existsSync(leasePath)) {
+        const lease = JSON.parse(fs.readFileSync(leasePath, 'utf8'));
+        if (Number.isSafeInteger(lease.pid) && typeof lease.startTime === 'number'
+            && getProcessStartTime(lease.pid) === lease.startTime) {
+            throw new Error('CODEX_SANDBOX_CONTROLLER_BUSY');
+        }
+        fs.unlinkSync(leasePath);
+    }
+    const parentStartTime = getProcessStartTime(process.pid);
+    if (!parentStartTime)
+        throw new Error('CODEX_SANDBOX_CONTROLLER_PROCESS_IDENTITY_INVALID');
+    const instanceDigest = crypto.randomBytes(32).toString('hex');
+    fs.writeFileSync(leasePath, `${JSON.stringify({
+        version: 1,
+        pid: process.pid,
+        startTime: parentStartTime,
+        taskId: input.taskId,
+        generation: control.generation,
+        instanceDigest
+    })}\n`, { mode: 0o600, flag: 'wx' });
+    const home = fs.mkdtempSync(path.join(runtimeRoot, `${key}-`));
+    fs.chmodSync(home, 0o700);
+    let cleaned = false;
+    const cleanup = () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        const relative = path.relative(runtimeRoot, home);
+        if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
+            fs.rmSync(home, { recursive: true, force: true });
+        }
+        try {
+            const lease = JSON.parse(fs.readFileSync(leasePath, 'utf8'));
+            if (lease.instanceDigest === instanceDigest)
+                fs.unlinkSync(leasePath);
+        }
+        catch {
+            // A missing or replaced lease is owned by another cleanup path.
+        }
+    };
+    try {
+        const auth = path.join(sourceHome, 'auth.json');
+        if (fs.existsSync(auth))
+            copyRegular(auth, path.join(home, 'auth.json'), 0o600);
+        const providerEnvironment = sanitizedConfig(path.join(sourceHome, 'config.toml'), path.join(home, 'config.toml'), sourceHome, home);
+        const hooks = path.join(repoRoot, '.codex', 'hooks.json');
+        const executor = path.join(repoRoot, '.codex', 'agents', 'agent-infra-lifecycle-executor.toml');
+        const reviewer = path.join(repoRoot, '.codex', 'agents', 'agent-infra-lifecycle-reviewer.toml');
+        copyRegular(hooks, path.join(home, 'hooks.json'), 0o600);
+        copyRegular(executor, path.join(home, 'agents', path.basename(executor)), 0o600);
+        copyRegular(reviewer, path.join(home, 'agents', path.basename(reviewer)), 0o600);
+        if (crypto.createHash('sha256').update(fs.readFileSync(path.join(home, 'hooks.json'))).digest('hex')
+            !== crypto.createHash('sha256').update(fs.readFileSync(hooks)).digest('hex')
+            || digestFiles([
+                path.join(home, 'agents', path.basename(executor)),
+                path.join(home, 'agents', path.basename(reviewer))
+            ]) !== digestFiles([executor, reviewer])) {
+            throw new Error('CODEX_SANDBOX_CONTROLLER_BUNDLE_MISMATCH');
+        }
+        const buildIdentity = computeLifecycleBuildIdentity(repoRoot);
+        const now = (options.now ?? Date.now)();
+        const context = Object.freeze({
+            version: 1,
+            taskId: input.taskId,
+            controlGeneration: control.generation,
+            controllerInstanceDigest: instanceDigest,
+            parentPid: process.pid,
+            parentStartTime,
+            issuedAt: now,
+            expiresAt: now + CONTEXT_TTL_MS,
+            buildIdentity,
+            hookDefinitionHash: crypto.createHash('sha256').update(fs.readFileSync(hooks)).digest('hex'),
+            lifecycleProfilesHash: digestFiles([executor, reviewer])
+        });
+        const contextPath = path.join(home, 'controller-context.json');
+        fs.writeFileSync(contextPath, `${JSON.stringify(context, null, 2)}\n`, { mode: 0o600 });
+        const shimDir = path.join(home, 'bin');
+        fs.mkdirSync(shimDir, { mode: 0o700 });
+        const internalCli = path.resolve(process.argv[1] ?? path.join(repoRoot, 'bin', 'internal-cli.ts'));
+        const source = internalCli.endsWith('.ts')
+            ? `#!/bin/sh\nexec ${shellQuote(process.execPath)} --experimental-strip-types ${shellQuote(internalCli)} "$@"\n`
+            : `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(internalCli)} "$@"\n`;
+        fs.writeFileSync(path.join(shimDir, 'agent-infra-internal'), source, { mode: 0o700 });
+        const policy = [
+            input.executorModel ? `--executor-model ${input.executorModel}` : '',
+            input.executorReasoningEffort ? `--executor-reasoning-effort ${input.executorReasoningEffort}` : '',
+            input.reviewerModel ? `--reviewer-model ${input.reviewerModel}` : '',
+            input.reviewerReasoningEffort ? `--reviewer-reasoning-effort ${input.reviewerReasoningEffort}` : ''
+        ].filter(Boolean).join(' ');
+        const prompt = `$run-task ${input.taskRef}${policy ? ` ${policy}` : ''}`;
+        const args = Object.freeze([
+            'exec',
+            '--enable', 'hooks',
+            '--enable', 'multi_agent',
+            '--dangerously-bypass-hook-trust',
+            '--dangerously-bypass-approvals-and-sandbox',
+            '--json',
+            '-C', repoRoot,
+            prompt
+        ]);
+        const env = isolatedEnvironment(home, shimDir, contextPath, input.taskId, control, providerEnvironment, options.environment ?? process.env);
+        return Object.freeze({
+            command: 'codex',
+            args,
+            env,
+            home,
+            contextPath,
+            context,
+            cleanup
+        });
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
+}
+function verifyCodexSandboxControllerContext(contextPath, taskId, options = {}) {
+    const stat = fs.lstatSync(contextPath);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0) {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+    }
+    const context = JSON.parse(fs.readFileSync(contextPath, 'utf8'));
+    const generation = options.generation ?? process.env.AGENT_INFRA_CONTROL_GENERATION;
+    if (context.version !== 1
+        || context.taskId !== taskId
+        || context.controlGeneration !== generation
+        || context.expiresAt < (options.now ?? Date.now())
+        || getProcessStartTime(context.parentPid) !== context.parentStartTime
+        || !isProcessAlive(context.parentPid)) {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+    }
+    const current = computeLifecycleBuildIdentity(options.repoRoot ?? process.cwd());
+    if (JSON.stringify(current) !== JSON.stringify(context.buildIdentity)) {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_BUNDLE_MISMATCH');
+    }
+    return Object.freeze(context);
+}
+async function runCodexSandboxController(input, options = {}) {
+    const prepared = prepareCodexSandboxController(input, options);
+    try {
+        const child = spawn(prepared.command, [...prepared.args], {
+            cwd: options.repoRoot ?? process.cwd(),
+            env: prepared.env,
+            stdio: 'inherit',
+            detached: process.platform !== 'win32'
+        });
+        let forceKill;
+        const terminate = () => {
+            if (child.pid && process.platform !== 'win32') {
+                try {
+                    process.kill(-child.pid, 'SIGTERM');
+                }
+                catch {
+                    child.kill('SIGTERM');
+                }
+            }
+            else
+                child.kill('SIGTERM');
+            forceKill = setTimeout(() => {
+                if (child.pid && process.platform !== 'win32') {
+                    try {
+                        process.kill(-child.pid, 'SIGKILL');
+                    }
+                    catch {
+                        child.kill('SIGKILL');
+                    }
+                }
+                else
+                    child.kill('SIGKILL');
+            }, 5_000);
+            forceKill.unref();
+        };
+        process.once('SIGINT', terminate);
+        process.once('SIGTERM', terminate);
+        try {
+            return await new Promise((resolve, reject) => {
+                child.once('error', reject);
+                child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+            });
+        }
+        finally {
+            if (forceKill)
+                clearTimeout(forceKill);
+            process.off('SIGINT', terminate);
+            process.off('SIGTERM', terminate);
+        }
+    }
+    finally {
+        prepared.cleanup();
+    }
+}
+export { prepareCodexSandboxController, runCodexSandboxController, verifyCodexSandboxControllerContext };
+//# sourceMappingURL=sandbox-controller.js.map

package/dist/lib/agent-clients/adapters/codex-lifecycle/store.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { createCodexLifecycleState, expireCodexLifecycleState, reduceCodexLifecycleEvent } from './evidence.js';
+import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.js';
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 1_000;
 const LOCK_STALE_MS = 30_000;
@@ -14,10 +15,12 @@ function readRecord(file) {
         || !Number.isSafeInteger(value.revision)
         || value.revision < 1
         || !value.state
-        || value.state.schemaVersion !== 1) {
+        || value.state.schemaVersion !== 1
+        || (value.spawnObservedAt != null && (typeof value.spawnObservedAt !== 'string'
+            || !Number.isFinite(Date.parse(value.spawnObservedAt))))) {
         throw new Error(`Codex lifecycle record '${path.basename(file)}' is invalid`);
     }
-    return value;
+    return Object.freeze({ ...value, spawnObservedAt: value.spawnObservedAt ?? null });
 }
 function recordFiles(root) {
     if (!fs.existsSync(root))
@@ -26,6 +29,15 @@ function recordFiles(root) {
         .filter((name) => /^[a-f0-9]{64}\.json$/.test(name))
         .map((name) => path.join(root, name));
 }
+function hasActiveCodexLifecycleEvidence(root, query) {
+    return recordFiles(root).map(readRecord).some((record) => {
+        const evidence = record.state.startEvidence;
+        return record.consumer === null
+            && ['start-ready', 'observed-terminal', 'stop-ready'].includes(record.state.status)
+            && evidence?.nativeAgent === query.nativeAgent
+            && evidence.hookDefinitionHash === query.hookDefinitionHash;
+    });
+}
 function writeRecord(file, record, expectedRevision) {
     const temp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
     fs.writeFileSync(temp, `${JSON.stringify(record, null, 2)}\n`, {
@@ -47,7 +59,7 @@ function writeRecord(file, record, expectedRevision) {
     }
 }
 function createCodexLifecycleStore(options) {
-    const root = options.root ?? path.join(process.cwd(), '.agents', 'workspace', '.runtime', 'codex-lifecycle');
+    const root = options.root ?? resolveAgentRuntimeStoreRoot({ store: 'lifecycle' });
     const now = options.now ?? (() => new Date().toISOString());
     fs.mkdirSync(root, { recursive: true, mode: 0o700 });
     fs.chmodSync(root, 0o700);
@@ -121,6 +133,7 @@ function createCodexLifecycleStore(options) {
     function apply(event) {
         return withWriteLock(() => {
             const file = locate(event);
+            const observedAt = now();
             const current = fs.existsSync(file)
                 ? readRecord(file)
                 : Object.freeze({
@@ -129,7 +142,8 @@ function createCodexLifecycleStore(options) {
                     state: createCodexLifecycleState(options.cliVersion),
                     consumer: null,
                     consumedAt: null,
-                    updatedAt: now()
+                    spawnObservedAt: null,
+                    updatedAt: observedAt
                 });
             if (current.consumer)
                 throw new Error(`Codex lifecycle evidence was already consumed by '${current.consumer}'`);
@@ -140,7 +154,10 @@ function createCodexLifecycleStore(options) {
                 state: nextState,
                 consumer: null,
                 consumedAt: null,
-                updatedAt: now()
+                spawnObservedAt: event.type === 'hook-spawn' && current.revision === 0
+                    ? observedAt
+                    : current.spawnObservedAt,
+                updatedAt: observedAt
             });
             writeRecord(file, next, current.revision);
             return Object.freeze({ path: file, revision: next.revision, state: next.state });
@@ -251,5 +268,5 @@ function createCodexLifecycleStore(options) {
     }
     return Object.freeze({ root, apply, applyToSpawn, consume, expireBefore, findByParent, read });
 }
-export { createCodexLifecycleStore };
+export { createCodexLifecycleStore, hasActiveCodexLifecycleEvidence };
 //# sourceMappingURL=store.js.map

package/dist/lib/decide.js

@@ -2,25 +2,44 @@ import { VERSION } from './version.js';
 import { parseTaskScope } from './task/command-options.js';
 import { applyHumanDecision } from './task/decision-intents.js';
 import { canonicalTimestamp } from './task/write.js';
+import { consumeHumanOverride, failureId } from './task/human-override.js';
+import { resolveTaskRef } from './task/resolve-ref.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task/task-execution-lock.js';
 function parseDecisionParts(parts) {
     const decision = [];
     let needsImplementation;
+    let overrideTicket;
+    let overrideTarget;
+    let overrideScope;
     for (let index = 0; index < parts.length; index += 1) {
-        if (parts[index] !== '--needs-implementation') {
-            decision.push(parts[index]);
-            continue;
+        const part = parts[index];
+        if (part === '--needs-implementation') {
+            if (needsImplementation !== undefined)
+                throw new Error("duplicate option '--needs-implementation'");
+            const value = parts[++index];
+            if (value !== 'true' && value !== 'false') {
+                throw new Error("--needs-implementation must be 'true' or 'false'");
+            }
+            needsImplementation = value === 'true';
         }
-        if (needsImplementation !== undefined)
-            throw new Error("duplicate option '--needs-implementation'");
-        const value = parts[++index];
-        if (value !== 'true' && value !== 'false') {
-            throw new Error("--needs-implementation must be 'true' or 'false'");
+        else if (part === '--override-ticket' || part === '--override-target' || part === '--override-scope') {
+            const value = parts[++index];
+            if (!value)
+                throw new Error(`${part} requires a value`);
+            if (part === '--override-ticket')
+                overrideTicket = value;
+            else if (part === '--override-target')
+                overrideTarget = value;
+            else
+                overrideScope = value;
+        }
+        else {
+            decision.push(parts[index]);
         }
-        needsImplementation = value === 'true';
     }
     if (decision.length === 0)
         throw new Error('decision content is required');
-    return { decision: decision.join(' '), needsImplementation };
+    return { decision: decision.join(' '), needsImplementation, overrideTicket, overrideTarget, overrideScope };
 }
 export async function decide(args, options = {}) {
     let scope;
@@ -79,19 +98,54 @@ export async function decide(args, options = {}) {
     try {
         const parsedDecision = parseDecisionParts(decisionParts);
         const now = (options.now ?? canonicalTimestamp)();
-        const result = applyHumanDecision({
+        const request = {
             taskRef, selector, decision: parsedDecision.decision,
             needsImplementation: parsedDecision.needsImplementation
-        }, {
+        };
+        const writeOptions = {
             repoRoot: options.repoRoot,
             metadataProvider: () => ({ timestamp: now, agentInfraVersion: options.version ?? VERSION })
-        });
+        };
+        const resolved = taskRef ? resolveTaskRef(taskRef, { repoRoot: options.repoRoot }) : null;
+        let result;
+        const execute = () => {
+            let current = applyHumanDecision(request, writeOptions);
+            if (current.status !== 'failed' || !parsedDecision.overrideTicket)
+                return current;
+            if (!parsedDecision.overrideTarget || !parsedDecision.overrideScope)
+                throw new Error('override ticket requires --override-target and --override-scope');
+            const consumed = consumeHumanOverride({
+                taskRef: resolved?.ok ? resolved.taskId : String(taskRef ?? ''),
+                ticketId: parsedDecision.overrideTicket,
+                failureId: failureId('decision-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
+                target: parsedDecision.overrideTarget,
+                scope: parsedDecision.overrideScope
+            }, {
+                ...writeOptions,
+                effectExecutor: (capability) => {
+                    const retried = applyHumanDecision(request, { ...writeOptions, manualOverride: capability });
+                    current = retried;
+                    return retried.status === 'failed' || retried.status === 'planned'
+                        ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no decision effect was committed' : `${retried.error?.code ?? 'DECISION_FAILED'}: ${retried.error?.message ?? 'manual decision effect failed'}` }
+                        : null;
+                }
+            });
+            if (consumed.status === 'failed')
+                throw new Error(consumed.error.message);
+            return current;
+        };
+        result = resolved?.ok
+            ? withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-decision', execute)
+            : execute();
         if (result.error)
             throw new Error(result.error.message);
         return 0;
     }
     catch (error) {
-        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        const message = error instanceof TaskExecutionLockError
+            ? `${error.code}: ${error.message}`
+            : error instanceof Error ? error.message : String(error);
+        process.stderr.write(`Error: ${message}\n`);
         return 1;
     }
 }

package/dist/lib/defaults.json

@@ -56,7 +56,6 @@
             ".agents/skills/",
             ".agents/templates/",
             ".agents/workflows/",
-            ".agents/workspace/README.md",
             ".git-hooks/check-large-files.cjs",
             ".git-hooks/check-version-format.sh",
             ".github/scripts/",
@@ -84,6 +83,15 @@
             ".git-hooks/pre-commit",
             ".gitignore"
         ],
-        "ejected": []
+        "ejected": [],
+        "retiredManaged": [
+            {
+                "path": ".agents/workspace/README.md",
+                "templateHashes": [
+                    "sha256:967b27ca4008154c5abf99a1df728242f80ed3ace9bd98eb2828bc1c76af826c",
+                    "sha256:15aa21942cf2a1396d27834f1d3d723b61a46f8d14600b706f39f3bebc21aea3"
+                ]
+            }
+        ]
     }
 }

package/dist/lib/git/workflow.js

@@ -12,6 +12,9 @@ function value(runner, cwd, args, trim = true) {
     const result = run(runner, cwd, args);
     return result.status === 0 ? (trim ? result.stdout.trim() : result.stdout.replace(/\n$/, '')) : null;
 }
+function nulPaths(output) {
+    return output.split('\0').filter(Boolean);
+}
 function cleanMessage(message) {
     return message.replace(/(https?:\/\/)[^\s/@:]+(?::[^\s/@]*)?@/gi, '$1***@').trim();
 }
@@ -64,9 +67,33 @@ function commitExplicitPaths(input, runner = defaultRunner) {
     const unrelatedStaged = before.snapshot.staged.filter((candidate) => !selected.has(candidate));
     if (unrelatedStaged.length > 0)
         return { status: 'failed', changed: false, snapshot: before.snapshot, operations: [], error: { code: 'GIT_STAGED_SCOPE_MISMATCH', message: `Unrelated staged paths: ${unrelatedStaged.join(', ')}` } };
-    const add = run(runner, input.cwd, ['add', '--', ...input.paths]);
-    if (add.status !== 0)
-        return { status: 'failed', changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'failed', message: add.stderr.trim() }], error: { code: 'GIT_STAGE_FAILED', message: add.stderr.trim() } };
+    const stageFailure = (message) => ({ status: 'failed', changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'failed', message }], error: { code: 'GIT_STAGE_FAILED', message } });
+    const indexed = run(runner, input.cwd, ['ls-files', '-z', '--', ...input.paths]);
+    if (indexed.status !== 0)
+        return stageFailure(indexed.stderr.trim());
+    const headed = run(runner, input.cwd, ['ls-tree', '-r', '--name-only', '-z', 'HEAD', '--', ...input.paths]);
+    if (headed.status !== 0)
+        return stageFailure(headed.stderr.trim());
+    const indexedPaths = new Set(nulPaths(indexed.stdout));
+    const headPaths = new Set(nulPaths(headed.stdout));
+    const trackedPaths = [];
+    const addPaths = [];
+    for (const candidate of input.paths) {
+        if (indexedPaths.has(candidate))
+            trackedPaths.push(candidate);
+        else if (!headPaths.has(candidate) || fs.existsSync(path.join(input.cwd, candidate)))
+            addPaths.push(candidate);
+    }
+    if (trackedPaths.length > 0) {
+        const update = run(runner, input.cwd, ['add', '-u', '--', ...trackedPaths]);
+        if (update.status !== 0)
+            return stageFailure(update.stderr.trim());
+    }
+    if (addPaths.length > 0) {
+        const add = run(runner, input.cwd, ['add', '--', ...addPaths]);
+        if (add.status !== 0)
+            return stageFailure(add.stderr.trim());
+    }
     const staged = run(runner, input.cwd, ['diff', '--cached', '--quiet', '--']);
     if (staged.status === 0)
         return { status: 'no-op', changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'no-op' }], error: null };