codex-workflow-v2 2.0.0-alpha.7.2.1 → 2.0.0-beta.2

package/dist/src/beta1/project-transaction.js

@@ -0,0 +1,297 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { WorkflowError } from '../errors.js';
+import { ensureDirectory, writeJsonAtomic, writeTextAtomic } from '../fs-utils.js';
+const TRANSACTION_ID = /^[a-z0-9][a-z0-9-]{7,127}$/;
+const activeProjectRoots = new Set();
+export function applyProjectTransaction(options) {
+    recoverProjectTransactions(options.projectRoot, options.projectId);
+    validateTransactionId(options.transactionId);
+    if (!options.kind.trim())
+        throw new WorkflowError('INVALID_ARGUMENT', 'Project transaction kind is required.');
+    if (options.targets.length === 0)
+        throw new WorkflowError('INVALID_ARGUMENT', 'Project transaction requires targets.');
+    const paths = options.targets.map((target) => normalizeTargetPath(target.path));
+    if (new Set(paths).size !== paths.length) {
+        throw new WorkflowError('INVALID_ARGUMENT', 'Project transaction target paths must be unique.');
+    }
+    const journal = {
+        schemaVersion: 1,
+        transactionId: options.transactionId,
+        kind: options.kind.trim(),
+        projectId: options.projectId,
+        phase: 'prepared',
+        recoveryMode: 'roll-forward',
+        ownerPid: process.pid,
+        ownerHostname: os.hostname(),
+        targets: options.targets.map((target, index) => ({
+            path: paths[index],
+            preimage: captureSnapshot(resolveTarget(options.projectRoot, paths[index])),
+            staged: snapshotFromContent(target.content),
+        })),
+        preparedAt: options.now.toISOString(),
+        updatedAt: options.now.toISOString(),
+    };
+    writeJournal(options.projectRoot, journal);
+    const activeKey = path.resolve(options.projectRoot);
+    activeProjectRoots.add(activeKey);
+    try {
+        writeJournal(options.projectRoot, { ...journal, phase: 'applying', updatedAt: options.now.toISOString() });
+        journal.targets.forEach((target, index) => {
+            restoreSnapshot(resolveTarget(options.projectRoot, target.path), target.staged);
+            options.afterTargetWrite?.(index, options.targets[index]);
+        });
+        options.validate?.();
+        writeJournal(options.projectRoot, { ...journal, phase: 'applied', updatedAt: options.now.toISOString() });
+        removeJournal(options.projectRoot, options.transactionId);
+    }
+    catch (error) {
+        rollback(options.projectRoot, journal);
+        throw error;
+    }
+    finally {
+        activeProjectRoots.delete(activeKey);
+    }
+}
+export function recoverProjectTransactions(projectRoot, projectId) {
+    if (activeProjectRoots.has(path.resolve(projectRoot)))
+        return [];
+    const directory = transactionDirectory(projectRoot);
+    if (!existsSync(directory))
+        return [];
+    const recovered = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true }).filter((item) => item.isFile() && item.name.endsWith('.json'))) {
+        const file = path.join(directory, entry.name);
+        const journal = parseJournal(file, projectRoot, projectId);
+        if ((journal.phase === 'prepared' || journal.phase === 'applying') && journal.ownerHostname === os.hostname() && processIsAlive(journal.ownerPid)) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'A project transaction is still owned by a live process.', {
+                transactionId: journal.transactionId,
+                kind: journal.kind,
+                ownerPid: journal.ownerPid,
+                requiredAction: 'Wait for the active command to finish, or run doctor after the owner process exits.',
+            });
+        }
+        if (journal.phase === 'prepared' || journal.phase === 'rolled_back') {
+            rollback(projectRoot, journal);
+            recovered.push(journal.transactionId);
+            continue;
+        }
+        if (journal.phase === 'applied') {
+            if (journal.recoveryMode === 'roll-forward') {
+                for (const target of journal.targets)
+                    restoreSnapshot(resolveTarget(projectRoot, target.path), target.staged);
+            }
+            removeJournal(projectRoot, journal.transactionId);
+            recovered.push(journal.transactionId);
+            continue;
+        }
+        if (journal.recoveryMode === 'roll-back') {
+            rollback(projectRoot, journal);
+            recovered.push(journal.transactionId);
+            continue;
+        }
+        for (const target of journal.targets) {
+            const current = captureSnapshot(resolveTarget(projectRoot, target.path));
+            if (!snapshotsEqual(current, target.preimage) && !snapshotsEqual(current, target.staged)) {
+                throw new WorkflowError('STATE_CORRUPT', 'Project transaction target diverged during recovery.', {
+                    transactionId: journal.transactionId,
+                    target: target.path,
+                });
+            }
+        }
+        for (const target of journal.targets)
+            restoreSnapshot(resolveTarget(projectRoot, target.path), target.staged);
+        removeJournal(projectRoot, journal.transactionId);
+        recovered.push(journal.transactionId);
+    }
+    return recovered;
+}
+export function runRollbackProjectTransaction(options) {
+    recoverProjectTransactions(options.projectRoot, options.projectId);
+    validateTransactionId(options.transactionId);
+    const paths = options.targetPaths.map(normalizeTargetPath);
+    if (paths.length === 0 || new Set(paths).size !== paths.length) {
+        throw new WorkflowError('INVALID_ARGUMENT', 'Rollback project transaction requires unique targets.');
+    }
+    const targets = paths.map((targetPath) => {
+        const preimage = captureSnapshot(resolveTarget(options.projectRoot, targetPath));
+        return { path: targetPath, preimage, staged: preimage };
+    });
+    const journal = {
+        schemaVersion: 1,
+        transactionId: options.transactionId,
+        kind: options.kind,
+        projectId: options.projectId,
+        phase: 'prepared',
+        recoveryMode: 'roll-back',
+        ownerPid: process.pid,
+        ownerHostname: os.hostname(),
+        targets,
+        preparedAt: options.now.toISOString(),
+        updatedAt: options.now.toISOString(),
+    };
+    const activeKey = path.resolve(options.projectRoot);
+    writeJournal(options.projectRoot, journal);
+    activeProjectRoots.add(activeKey);
+    try {
+        writeJournal(options.projectRoot, { ...journal, phase: 'applying', updatedAt: options.now.toISOString() });
+        const result = options.mutate();
+        options.validate?.(result);
+        writeJournal(options.projectRoot, { ...journal, phase: 'applied', updatedAt: options.now.toISOString() });
+        removeJournal(options.projectRoot, journal.transactionId);
+        return result;
+    }
+    catch (error) {
+        rollback(options.projectRoot, journal);
+        throw error;
+    }
+    finally {
+        activeProjectRoots.delete(activeKey);
+    }
+}
+export function listProjectTransactions(projectRoot, projectId) {
+    const directory = transactionDirectory(projectRoot);
+    if (!existsSync(directory))
+        return [];
+    return readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+        .map((entry) => parseJournal(path.join(directory, entry.name), projectRoot, projectId))
+        .map(({ transactionId, kind, phase, preparedAt }) => ({ transactionId, kind, phase, preparedAt }));
+}
+function rollback(projectRoot, journal) {
+    for (const target of journal.targets)
+        restoreSnapshot(resolveTarget(projectRoot, target.path), target.preimage);
+    writeJournal(projectRoot, { ...journal, phase: 'rolled_back', updatedAt: new Date().toISOString() });
+    removeJournal(projectRoot, journal.transactionId);
+}
+function transactionDirectory(projectRoot) {
+    return path.join(projectRoot, '.transactions-beta1');
+}
+function journalPath(projectRoot, transactionId) {
+    validateTransactionId(transactionId);
+    return path.join(transactionDirectory(projectRoot), `${transactionId}.json`);
+}
+function writeJournal(projectRoot, journal) {
+    ensureDirectory(transactionDirectory(projectRoot));
+    writeJsonAtomic(journalPath(projectRoot, journal.transactionId), journal);
+}
+function removeJournal(projectRoot, transactionId) {
+    rmSync(journalPath(projectRoot, transactionId), { force: true });
+}
+function parseJournal(file, projectRoot, projectId) {
+    let value;
+    try {
+        value = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new WorkflowError('STATE_CORRUPT', `Cannot read project transaction journal: ${file}`, {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    const journal = value;
+    if (journal.schemaVersion !== 1 || journal.projectId !== projectId || !journal.transactionId || !journal.kind
+        || !['roll-forward', 'roll-back'].includes(journal.recoveryMode ?? '')
+        || !Number.isInteger(journal.ownerPid) || (journal.ownerPid ?? 0) < 1 || !journal.ownerHostname
+        || !['prepared', 'applying', 'applied', 'rolled_back'].includes(journal.phase ?? '') || !Array.isArray(journal.targets)) {
+        throw new WorkflowError('STATE_CORRUPT', `Invalid project transaction journal: ${file}`);
+    }
+    validateTransactionId(journal.transactionId);
+    const expectedFile = journalPath(projectRoot, journal.transactionId);
+    if (path.resolve(file) !== path.resolve(expectedFile)) {
+        throw new WorkflowError('STATE_CORRUPT', `Project transaction journal filename mismatch: ${file}`);
+    }
+    for (const target of journal.targets) {
+        normalizeTargetPath(target.path);
+        validateSnapshot(target.preimage);
+        validateSnapshot(target.staged);
+    }
+    return journal;
+}
+function normalizeTargetPath(value) {
+    const normalized = value.split(path.sep).join('/');
+    if (!normalized || path.isAbsolute(normalized) || normalized.split('/').some((part) => !part || part === '.' || part === '..')) {
+        throw new WorkflowError('INVALID_ARGUMENT', `Invalid project transaction target: ${value}`);
+    }
+    if (normalized === '.transactions-beta1' || normalized.startsWith('.transactions-beta1/')) {
+        throw new WorkflowError('INVALID_ARGUMENT', 'Project transaction cannot target its journal directory.');
+    }
+    return normalized;
+}
+function resolveTarget(projectRoot, relativePath) {
+    const root = path.resolve(projectRoot);
+    const target = path.resolve(root, normalizeTargetPath(relativePath));
+    if (!target.startsWith(`${root}${path.sep}`))
+        throw new WorkflowError('INVALID_ARGUMENT', 'Project transaction target escaped project root.');
+    let current = root;
+    for (const part of path.relative(root, path.dirname(target)).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        if (existsSync(current) && lstatSync(current).isSymbolicLink()) {
+            throw new WorkflowError('STATE_CORRUPT', `Project transaction target traverses a symlink: ${relativePath}`);
+        }
+    }
+    if (existsSync(target) && lstatSync(target).isSymbolicLink()) {
+        throw new WorkflowError('STATE_CORRUPT', `Project transaction target is a symlink: ${relativePath}`);
+    }
+    return target;
+}
+function captureSnapshot(file) {
+    if (!existsSync(file))
+        return { exists: false, contentHash: null, contentBase64: null };
+    const content = readFileSync(file);
+    return { exists: true, contentHash: sha256(content), contentBase64: content.toString('base64') };
+}
+function snapshotFromContent(content) {
+    if (content === null)
+        return { exists: false, contentHash: null, contentBase64: null };
+    const normalized = Buffer.from(content.endsWith('\n') ? content : `${content}\n`);
+    return { exists: true, contentHash: sha256(normalized), contentBase64: normalized.toString('base64') };
+}
+function restoreSnapshot(file, snapshot) {
+    validateSnapshot(snapshot);
+    if (!snapshot.exists) {
+        rmSync(file, { force: true });
+        return;
+    }
+    writeTextAtomic(file, Buffer.from(snapshot.contentBase64, 'base64').toString('utf8'));
+    if (!snapshotsEqual(captureSnapshot(file), snapshot)) {
+        throw new WorkflowError('STATE_CORRUPT', `Project transaction snapshot restore failed: ${file}`);
+    }
+}
+function validateSnapshot(snapshot) {
+    if (!snapshot || typeof snapshot !== 'object' || typeof snapshot.exists !== 'boolean') {
+        throw new WorkflowError('STATE_CORRUPT', 'Invalid project transaction snapshot.');
+    }
+    if (!snapshot.exists) {
+        if (snapshot.contentHash !== null || snapshot.contentBase64 !== null)
+            throw new WorkflowError('STATE_CORRUPT', 'Absent snapshot contains data.');
+        return;
+    }
+    if (!snapshot.contentHash || !/^[a-f0-9]{64}$/.test(snapshot.contentHash) || snapshot.contentBase64 === null) {
+        throw new WorkflowError('STATE_CORRUPT', 'Existing project transaction snapshot is incomplete.');
+    }
+    if (sha256(Buffer.from(snapshot.contentBase64, 'base64')) !== snapshot.contentHash) {
+        throw new WorkflowError('STATE_CORRUPT', 'Project transaction snapshot hash mismatch.');
+    }
+}
+function snapshotsEqual(left, right) {
+    return left.exists === right.exists && left.contentHash === right.contentHash;
+}
+function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function validateTransactionId(value) {
+    if (!TRANSACTION_ID.test(value))
+        throw new WorkflowError('INVALID_ARGUMENT', `Invalid project transaction id: ${value}`);
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'EPERM');
+    }
+}
+//# sourceMappingURL=project-transaction.js.map

package/dist/src/beta1/project-transaction.js.map

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

package/dist/src/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
@@ -12,6 +13,118 @@ import { launchStrictReviewer } from './reviewer.js';
 import { WorkflowService } from './workflow.js';
 import { PACKAGE_NAME, PACKAGE_VERSION } from './version.js';
 import { PROTOCOL_VERSION, STATE_SCHEMA_VERSION } from './contracts.js';
+const CLI_ACTIONS = {
+    gateway: ['handshake'],
+    update: ['preflight', 'rescue-preflight'],
+    delegation: ['prepare', 'grant', 'list', 'show', 'revoke'],
+    'project-memory': ['scan', 'show', 'status', 'approve', 'reconcile'],
+    state: ['migrate', 'adoption-prepare', 'adoption-apply'],
+    graph: ['prepare', 'status', 'refresh-request', 'bind', 'fallback'],
+    discovery: ['start', 'update', 'show', 'materialize'],
+    task: [
+        'show',
+        'replacement-materialize',
+        'plan-set',
+        'knowledge-rebind',
+        'context-refresh',
+        'authorize',
+        'plan-risk-audit',
+        'start',
+        'run',
+        'step-complete',
+        'submit',
+        'review-record',
+        'review-launch',
+        'step-review',
+        'corrective-decision-recover',
+        'remediation-mode-recover',
+        'corrective-decision',
+        'handoff',
+        'handoff-prepare',
+        'handoff-show',
+        'claim',
+        'handback',
+        'handback-create',
+        'result-set',
+        'accept',
+        'sync-base',
+        'merge',
+        'merge-confirm',
+    ],
+    milestone: [
+        'recover',
+        'show',
+        'plan-set',
+        'scope-change-prepare',
+        'scope-change-apply',
+        'autonomy-prepare',
+        'autonomy-grant',
+        'autonomy-evolve',
+        'authorize',
+        'validate',
+        'accept',
+        'cancel',
+    ],
+    locks: ['inspect', 'repair'],
+};
+const CLI_HELP_SPECS = {
+    'milestone authorize': {
+        requiredOptions: ['--id', '--expected-revision'],
+        optionalOptions: ['--actor', '--reason', '--delegation-grant', '--repo', '--json'],
+    },
+    'milestone validate': {
+        requiredOptions: ['--id', '--expected-revision'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'milestone accept': {
+        requiredOptions: ['--id', '--expected-revision', '--actor', '--confirmation-code'],
+        optionalOptions: ['--delegation-grant', '--repo', '--json'],
+    },
+    'task plan-set': {
+        requiredOptions: ['--id', '--expected-revision', '--file', '--risk-audit-file'],
+        optionalOptions: ['--corrective-audit-file', '--repo', '--json'],
+    },
+    'task authorize': {
+        requiredOptions: ['--id', '--expected-revision'],
+        optionalOptions: ['--actor', '--reason', '--delegation-grant', '--repo', '--json'],
+    },
+    'task start': {
+        requiredOptions: ['--id', '--expected-revision', '--workspace-owner'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'task run': {
+        requiredOptions: ['--id', '--step', '--expected-revision'],
+        optionalOptions: ['--owner', '--writer-token', '--repo', '--json'],
+    },
+    'task step-complete': {
+        requiredOptions: ['--id', '--step', '--expected-revision', '--writer-token'],
+        optionalOptions: ['--note', '--actor', '--repo', '--json'],
+    },
+    'task submit': {
+        requiredOptions: ['--id', '--expected-revision', '--writer-token'],
+        optionalOptions: ['--actor', '--repo', '--json'],
+    },
+    'task review-launch': {
+        requiredOptions: ['--id', '--expected-revision'],
+        optionalOptions: ['--actor', '--writer-token', '--repo', '--json'],
+    },
+    'task result-set': {
+        requiredOptions: ['--id', '--expected-revision', '--summary'],
+        optionalOptions: ['--limitation', '--repo', '--json'],
+    },
+    'task accept': {
+        requiredOptions: ['--id', '--expected-revision'],
+        optionalOptions: ['--actor', '--delegation-grant', '--repo', '--json'],
+    },
+    'task merge': {
+        requiredOptions: ['--id', '--expected-revision', '--writer-token'],
+        optionalOptions: ['--actor', '--repo', '--json'],
+    },
+    'task merge-confirm': {
+        requiredOptions: ['--id', '--expected-revision', '--writer-token'],
+        optionalOptions: ['--actor', '--repo', '--json'],
+    },
+};
 function parseArguments(argv) {
     const positionals = [];
     const options = new Map();
@@ -37,6 +150,55 @@ function parseArguments(argv) {
 function option(args, name) {
     return args.options.get(name)?.at(-1);
 }
+function cliHelp(args) {
+    const [noun, action] = args.positionals;
+    if (!noun) {
+        return {
+            kind: 'cli-help',
+            readOnly: true,
+            scope: 'top-level',
+            usage: 'codex-workflow <command> [action] [options]',
+            commands: ['doctor', 'status', 'next', ...Object.keys(CLI_ACTIONS)],
+        };
+    }
+    if (!action) {
+        if (['doctor', 'status', 'next'].includes(noun)) {
+            return {
+                kind: 'cli-help',
+                readOnly: true,
+                scope: 'command',
+                command: noun,
+                usage: `codex-workflow ${noun} [--repo <path>] [--json]`,
+                requiredOptions: [],
+                optionalOptions: ['--repo', '--json'],
+                exactOptionContractAvailable: true,
+            };
+        }
+        return {
+            kind: 'cli-help',
+            readOnly: true,
+            scope: 'command',
+            command: noun,
+            usage: `codex-workflow ${noun} <action> [options]`,
+            actions: CLI_ACTIONS[noun] ?? [],
+        };
+    }
+    const command = `${noun} ${action}`;
+    const spec = CLI_HELP_SPECS[command];
+    return {
+        kind: 'cli-help',
+        readOnly: true,
+        scope: 'action',
+        command,
+        usage: spec
+            ? ['codex-workflow', noun, action, ...spec.requiredOptions.map((name) => `${name} <value>`), '[options]'].join(' ')
+            : `codex-workflow ${noun} ${action} [options]`,
+        requiredOptions: spec?.requiredOptions ?? null,
+        optionalOptions: spec?.optionalOptions ?? null,
+        exactOptionContractAvailable: Boolean(spec),
+        ...(spec ? {} : { note: 'Consult the packaged protocol for this action option contract.' }),
+    };
+}
 function required(args, name) {
     const value = option(args, name)?.trim();
     if (!value)
@@ -135,6 +297,7 @@ function workflowCapabilities() {
         'alpha6-adoption-posture-v1',
         'alpha6-strict-review-rescue-v1',
         'milestone-initial-assembly-v1',
+        'milestone-initial-assembly-navigation-v2',
         'milestone-autonomy-contract-v1',
         'milestone-autonomy-content-refresh-v1',
         'milestone-autonomous-membership-evolution-v1',
@@ -143,10 +306,14 @@ function workflowCapabilities() {
         'corrective-decision-context-recovery-v1',
         'remediation-mode-recovery-v1',
         'plan-proof-obligations-v1',
+        'terminal-task-replacement-transaction-v1',
+        'project-composite-transaction-journal-v1',
     ];
 }
 async function dispatch(args) {
     const [noun, action] = args.positionals;
+    if (args.options.has('help'))
+        return cliHelp(args);
     const repo = repository(args);
     if (noun === 'gateway' && action === 'handshake') {
         return {
@@ -320,6 +487,9 @@ async function dispatch(args) {
         const context = workflow.context(repo);
         return context.store.readTask(context.identity.projectId, required(args, 'id'));
     }
+    if (noun === 'task' && action === 'replacement-materialize') {
+        return workflow.replaceSplitRequiredTask(repo, required(args, 'id'), revision(args), required(args, 'discovery'), positiveIntegerOption(args, 'expected-discovery-revision'), positiveIntegerOption(args, 'expected-milestone-revision'), required(args, 'title'), option(args, 'actor') ?? 'user');
+    }
     if (noun === 'task' && action === 'plan-set') {
         return workflow.setTaskPlan(repo, required(args, 'id'), revision(args), jsonFile(args), option(args, 'corrective-audit-file')
             ? jsonFile(args, 'corrective-audit-file')
@@ -345,7 +515,24 @@ async function dispatch(args) {
         return workflow.startTask(repo, required(args, 'id'), revision(args), owner);
     }
     if (noun === 'task' && action === 'run') {
-        return workflow.runStep(repo, required(args, 'id'), required(args, 'step'), revision(args), option(args, 'owner') ?? 'worker', option(args, 'writer-token') ?? null);
+        const outcome = workflow.runStep(repo, required(args, 'id'), required(args, 'step'), revision(args), option(args, 'owner') ?? 'worker', option(args, 'writer-token') ?? null);
+        const { token, ...lease } = outcome.lease;
+        const { writerToken: _writerToken, ...envelope } = outcome.envelope;
+        return {
+            writerLeaseReceipt: {
+                token,
+                kind: 'writer-lease',
+                owner: outcome.lease.owner,
+                action: 'task step-complete',
+                option: '--writer-token',
+                source: 'task run',
+                sensitive: true,
+                oneTime: false,
+            },
+            task: outcome.task,
+            lease,
+            envelope,
+        };
     }
     if (noun === 'task' && action === 'step-complete') {
         return workflow.completeStep(repo, required(args, 'id'), required(args, 'step'), revision(args), required(args, 'writer-token'), repeated(args, 'note'), option(args, 'actor'));
@@ -370,10 +557,14 @@ async function dispatch(args) {
         }
         const envelope = workflow.taskContext(repo, id, 'independent-reviewer');
         const launch = launchStrictReviewer(context.identity.repositoryRoot, task, context.store.taskRoot(task.projectId, task.id), envelope);
+        // The independent reviewer identity belongs to the strict reviewer payload. CLI --actor
+        // remains the lifecycle mutation actor, such as the current C1 claimant.
         const saved = workflow.recordReview(repo, id, expectedRevision, launch.review, option(args, 'actor'), option(args, 'writer-token') ?? null);
         return { launch, task: saved };
     }
     if (noun === 'task' && action === 'step-review') {
+        // Strict Step Review launches and records the isolated reviewer inside Core. CLI --actor
+        // remains the lifecycle actor from next, typically the active C1 claimant.
         return workflow.reviewStep(repo, required(args, 'id'), required(args, 'step'), revision(args), undefined, option(args, 'actor'), option(args, 'writer-token') ?? null);
     }
     if (noun === 'task' && action === 'corrective-decision-recover') {
@@ -386,13 +577,45 @@ async function dispatch(args) {
         return workflow.recordStepCorrectiveDecision(repo, required(args, 'id'), required(args, 'step'), revision(args), jsonFile(args), option(args, 'actor'), option(args, 'writer-token') ?? null);
     }
     if (noun === 'task' && (action === 'handoff' || action === 'handoff-prepare')) {
-        return workflow.handoffTask(repo, required(args, 'id'), revision(args), required(args, 'actor'), option(args, 'target-actor') ?? defaultTaskWorkerActor(required(args, 'id')), required(args, 'reason'), option(args, 'writer-token') ?? null, option(args, 'delegation-grant') ?? null, option(args, 'expires-at') ?? null);
+        const outcome = workflow.handoffTask(repo, required(args, 'id'), revision(args), required(args, 'actor'), option(args, 'target-actor') ?? defaultTaskWorkerActor(required(args, 'id')), required(args, 'reason'), option(args, 'writer-token') ?? null, option(args, 'delegation-grant') ?? null, option(args, 'expires-at') ?? null);
+        const { claimToken, ...bundle } = outcome.bundle;
+        return {
+            credentialHandoff: {
+                token: claimToken,
+                kind: 'claim-token',
+                targetActor: outcome.bundle.delegate,
+                action: 'task claim',
+                option: '--claim-token',
+                source: 'task handoff-prepare',
+                sensitive: true,
+                oneTime: true,
+            },
+            task: outcome.task,
+            event: outcome.event,
+            bundle,
+        };
     }
     if (noun === 'task' && action === 'handoff-show') {
         return workflow.showTaskHandoff(repo, required(args, 'id'));
     }
     if (noun === 'task' && action === 'claim') {
-        return workflow.claimTask(repo, required(args, 'id'), revision(args), required(args, 'actor'), required(args, 'claim-token'), option(args, 'writer-token') ?? null);
+        const outcome = workflow.claimTask(repo, required(args, 'id'), revision(args), required(args, 'actor'), required(args, 'claim-token'), option(args, 'writer-token') ?? null);
+        const { token, ...lease } = outcome.lease;
+        return {
+            writerLeaseReceipt: {
+                token,
+                kind: 'writer-lease',
+                owner: outcome.lease.owner,
+                action: 'task run',
+                option: '--writer-token',
+                source: 'task claim',
+                sensitive: true,
+                oneTime: false,
+            },
+            task: outcome.task,
+            event: outcome.event,
+            lease,
+        };
     }
     if (noun === 'task' && (action === 'handback' || action === 'handback-create')) {
         return workflow.handbackTask(repo, required(args, 'id'), revision(args), required(args, 'actor'), required(args, 'reason'), option(args, 'writer-token') ?? null, repeated(args, 'limitation'), action === 'handback-create'
@@ -451,7 +674,19 @@ async function dispatch(args) {
     if (noun === 'locks' && (action === 'inspect' || action === 'repair')) {
         const context = workflow.context(repo);
         const id = required(args, 'id');
-        return action === 'inspect' ? context.locks.inspect(id) : context.locks.repairStale(id);
+        const lease = action === 'inspect' ? context.locks.inspect(id) : context.locks.repairStale(id);
+        return lease ? {
+            schemaVersion: lease.schemaVersion,
+            entityId: lease.entityId,
+            tokenFingerprint: createHash('sha256').update(lease.token).digest('hex').slice(0, 16),
+            owner: lease.owner,
+            pid: lease.pid,
+            hostname: lease.hostname,
+            acquiredAt: lease.acquiredAt,
+            heartbeatAt: lease.heartbeatAt,
+            expiresAt: lease.expiresAt,
+            repaired: action === 'repair',
+        } : null;
     }
     throw new WorkflowError('INVALID_ARGUMENT', 'Unknown command.', {
         command: args.positionals.join(' '),