codex-workflow-v2 2.0.0-beta.1 → 2.0.0-beta.11

package/dist/src/cli.js

@@ -1,18 +1,208 @@
 #!/usr/bin/env node
-import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { defaultTaskWorkerActor } from './alpha6/handoff.js';
+import { assertCliSuccessCredentialSafety, projectCliErrorMessage, projectCliErrorValue, UnsafeCredentialOutputError, } from './credential-output.js';
 import { integrationDiagnostics } from './diagnostics.js';
 import { WorkflowError } from './errors.js';
 import { prepareGraphView } from './graph.js';
 import { migrateState } from './migration.js';
-import { changedFiles, currentBranch, isClean } from './repository.js';
+import { changedFiles, currentBranch, isClean, resolveRepositoryIdentity } from './repository.js';
 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', 'dependency-provenance-preflight', 'dependency-provenance-recover'],
+    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',
+        'review-packet',
+        'review-sealed-record',
+        'step-review',
+        'step-review-packet',
+        'step-review-record',
+        'corrective-decision-recover',
+        'remediation-mode-recover',
+        'plan-integrity-recover',
+        'corrective-decision',
+        'corrective-yield',
+        'corrective-yield-recover',
+        'corrective-replan-prepare',
+        'corrective-replan-confirm',
+        'corrective-replan-execute',
+        'corrective-replan-recover',
+        'handoff',
+        'handoff-prepare',
+        'handoff-replace',
+        'handoff-show',
+        'claim',
+        'writer-credential-replace',
+        'handback',
+        'handback-create',
+        'result-set',
+        'accept',
+        'sync-base',
+        'merge',
+        'merge-confirm',
+    ],
+    milestone: [
+        'recover',
+        'show',
+        'progress',
+        '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 = {
+    'update dependency-provenance-preflight': {
+        requiredOptions: ['--id'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'update dependency-provenance-recover': {
+        requiredOptions: ['--id', '--expected-revision', '--actor', '--reason'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'milestone progress': {
+        requiredOptions: ['--id'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    '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 handoff-replace': {
+        requiredOptions: ['--id', '--expected-revision', '--actor', '--target-actor', '--reason'],
+        optionalOptions: ['--delegation-grant', '--expires-at', '--repo', '--json'],
+    },
+    'task writer-credential-replace': {
+        requiredOptions: ['--id', '--expected-revision', '--actor'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'task corrective-yield': {
+        requiredOptions: ['--id', '--expected-revision', '--actor', '--writer-token', '--reason'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'task plan-integrity-recover': {
+        requiredOptions: ['--id', '--step', '--expected-revision', '--actor'],
+        optionalOptions: ['--writer-token', '--repo', '--json'],
+    },
+    'task corrective-yield-recover': {
+        requiredOptions: ['--id', '--transaction-id'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'task corrective-replan-prepare': {
+        requiredOptions: ['--id', '--file'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'task corrective-replan-confirm': {
+        requiredOptions: ['--id', '--file', '--gate-file', '--confirmation-code'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'task corrective-replan-execute': {
+        requiredOptions: ['--id', '--file', '--credential-file'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'task corrective-replan-recover': {
+        requiredOptions: ['--id', '--transaction-id'],
+        optionalOptions: ['--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 review-packet': {
+        requiredOptions: ['--id', '--expected-revision'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'task review-sealed-record': {
+        requiredOptions: ['--id', '--expected-revision', '--actor', '--file'],
+        optionalOptions: ['--writer-token', '--repo', '--json'],
+    },
+    'task step-review-packet': {
+        requiredOptions: ['--id', '--step', '--expected-revision'],
+        optionalOptions: ['--repo', '--json'],
+    },
+    'task step-review-record': {
+        requiredOptions: ['--id', '--step', '--expected-revision', '--actor', '--file'],
+        optionalOptions: ['--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();
@@ -38,6 +228,58 @@ 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)) {
+            const taskSelector = noun === 'next' ? ['--task'] : [];
+            return {
+                kind: 'cli-help',
+                readOnly: true,
+                scope: 'command',
+                command: noun,
+                usage: noun === 'next'
+                    ? 'codex-workflow next [--task <task-id>] [--repo <path>] [--json]'
+                    : `codex-workflow ${noun} [--repo <path>] [--json]`,
+                requiredOptions: [],
+                optionalOptions: [...taskSelector, '--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)
@@ -121,6 +363,11 @@ function workflowCapabilities() {
         'task-context-refresh-v1',
         'corrective-plan-audit-v1',
         'safe-update-preflight-v1',
+        'bounded-dependency-provenance-recovery-v1',
+        'retained-reviewed-history-recovery-v1',
+        'milestone-progress-projection-v1',
+        'bounded-plan-integrity-recovery-v1',
+        'task-mechanical-feasibility-v1',
         'strict-reviewer-v1',
         'legacy-snapshot-v1',
         'plan-risk-audit-sidecar-v1',
@@ -128,6 +375,8 @@ function workflowCapabilities() {
         'step-remediation-circuit-breaker-sidecar-v1',
         'milestone-scope-change-sidecar-v1',
         'milestone-membership-integrity-v1',
+        'milestone-task-dependency-dag-v1',
+        'milestone-initial-plan-transaction-v1',
         'task-c1-handoff-sidecar-v1',
         'semantic-plan-risk-audit-v2',
         'guarded-remediation-hard-stop-v1',
@@ -136,6 +385,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',
@@ -144,12 +394,18 @@ function workflowCapabilities() {
         'corrective-decision-context-recovery-v1',
         'remediation-mode-recovery-v1',
         'plan-proof-obligations-v1',
-        'terminal-task-replacement-transaction-v1',
+        'structural-task-replacement-disabled-v1',
         'project-composite-transaction-journal-v1',
+        'corrective-yield-journal-v1',
+        'corrective-replan-journal-v1',
+        'corrective-replan-human-gate-v1',
+        'corrective-replan-protocol-v2',
     ];
 }
 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 {
@@ -162,19 +418,19 @@ async function dispatch(args) {
     }
     const workflow = new WorkflowService();
     if (noun === 'doctor') {
-        const context = workflow.context(repo);
-        const integration = integrationDiagnostics(context.identity.repositoryRoot);
+        const identity = resolveRepositoryIdentity(repo);
+        const integration = integrationDiagnostics(identity.repositoryRoot);
         const nodeSupported = Number(process.versions.node.split('.')[0]) >= 22;
         return {
             ok: nodeSupported && integration.localDependency.current,
             node: process.versions.node,
             requiredNode: '>=22',
-            repositoryRoot: context.identity.repositoryRoot,
-            projectId: context.identity.projectId,
-            stateRoot: context.store.root,
-            branch: currentBranch(context.identity.repositoryRoot),
-            clean: isClean(context.identity.repositoryRoot),
-            changedFiles: changedFiles(context.identity.repositoryRoot),
+            repositoryRoot: identity.repositoryRoot,
+            projectId: identity.projectId,
+            stateRoot: workflow.store.root,
+            branch: currentBranch(identity.repositoryRoot),
+            clean: isClean(identity.repositoryRoot),
+            changedFiles: changedFiles(identity.repositoryRoot),
             integration,
             limitations: [
                 'CLI diagnostics cannot prove that Codex enforced a role, model, sandbox, or read-only reviewer.',
@@ -185,12 +441,18 @@ async function dispatch(args) {
     if (noun === 'status')
         return workflow.status(repo);
     if (noun === 'next')
-        return workflow.next(repo);
+        return workflow.next(repo, option(args, 'task') ?? null);
     if (noun === 'update' && action === 'preflight')
         return workflow.updatePreflight(repo);
     if (noun === 'update' && action === 'rescue-preflight') {
         return workflow.alpha6StrictReviewRescuePreflight(repo);
     }
+    if (noun === 'update' && action === 'dependency-provenance-preflight') {
+        return workflow.dependencyProvenanceRecoveryPreflight(repo, required(args, 'id'));
+    }
+    if (noun === 'update' && action === 'dependency-provenance-recover') {
+        return workflow.recoverDependencyProvenance(repo, required(args, 'id'), revision(args), required(args, 'actor'), required(args, 'reason'));
+    }
     if (noun === 'delegation' && action === 'prepare') {
         return workflow.prepareDelegation(repo, jsonFile(args));
     }
@@ -198,12 +460,12 @@ async function dispatch(args) {
         return workflow.grantDelegation(repo, jsonFile(args), required(args, 'confirmation-code'));
     }
     if (noun === 'delegation' && action === 'list') {
-        const context = workflow.context(repo);
-        return context.store.listDelegations(context.identity.projectId);
+        const identity = resolveRepositoryIdentity(repo);
+        return workflow.store.listDelegations(identity.projectId);
     }
     if (noun === 'delegation' && action === 'show') {
-        const context = workflow.context(repo);
-        return context.store.readDelegation(context.identity.projectId, required(args, 'id'));
+        const identity = resolveRepositoryIdentity(repo);
+        return workflow.store.readDelegation(identity.projectId, required(args, 'id'));
     }
     if (noun === 'delegation' && action === 'revoke') {
         return workflow.revokeDelegation(repo, required(args, 'id'), revision(args), required(args, 'actor'), required(args, 'reason'));
@@ -306,8 +568,8 @@ async function dispatch(args) {
         return workflow.updateDiscovery(repo, required(args, 'id'), revision(args), patch);
     }
     if (noun === 'discovery' && action === 'show') {
-        const context = workflow.context(repo);
-        return context.store.readDiscovery(context.identity.projectId, required(args, 'id'));
+        const identity = resolveRepositoryIdentity(repo);
+        return workflow.store.readDiscovery(identity.projectId, required(args, 'id'));
     }
     if (noun === 'discovery' && action === 'materialize') {
         const kind = option(args, 'kind') ?? 'task';
@@ -320,8 +582,8 @@ async function dispatch(args) {
         throw new WorkflowError('INVALID_ARGUMENT', '--kind must be task or milestone.');
     }
     if (noun === 'task' && action === 'show') {
-        const context = workflow.context(repo);
-        return context.store.readTask(context.identity.projectId, required(args, 'id'));
+        const identity = resolveRepositoryIdentity(repo);
+        return workflow.store.readTask(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');
@@ -351,7 +613,32 @@ 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 { writerToken, ...envelope } = outcome.envelope;
+        if (outcome.writerCredential.disposition === 'issued' && !writerToken) {
+            throw new WorkflowError('STATE_CORRUPT', 'Fresh task run credential issuance did not return its protocol-v1 writer token.');
+        }
+        if (outcome.writerCredential.disposition === 'renewed' && writerToken !== null) {
+            throw new WorkflowError('STATE_CORRUPT', 'Renewed task run credential unexpectedly returned a writer token.');
+        }
+        return {
+            writerCredential: { disposition: outcome.writerCredential.disposition },
+            ...(writerToken ? {
+                writerLeaseReceipt: {
+                    token: writerToken,
+                    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: outcome.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'));
@@ -364,10 +651,10 @@ async function dispatch(args) {
         return workflow.recordReview(repo, required(args, 'id'), revision(args), review, option(args, 'actor'), option(args, 'writer-token') ?? null);
     }
     if (noun === 'task' && action === 'review-launch') {
-        const context = workflow.context(repo);
+        const identity = resolveRepositoryIdentity(repo);
         const id = required(args, 'id');
         const expectedRevision = revision(args);
-        const task = context.store.readTask(context.identity.projectId, id);
+        const task = workflow.store.readTask(identity.projectId, id);
         if (task.revision !== expectedRevision) {
             throw new WorkflowError('STATE_CONFLICT', `State revision conflict for ${id}`, {
                 expectedRevision,
@@ -375,30 +662,119 @@ 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);
+        const launch = launchStrictReviewer(identity.repositoryRoot, task, workflow.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 === 'review-packet') {
+        return workflow.prepareExternalTaskReview(repo, required(args, 'id'), revision(args));
+    }
+    if (noun === 'task' && action === 'review-sealed-record') {
+        return workflow.recordExternalTaskReview(repo, required(args, 'id'), revision(args), jsonFile(args), required(args, 'actor'), option(args, 'writer-token') ?? null);
+    }
     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 === 'step-review-packet') {
+        return workflow.prepareExternalStepReview(repo, required(args, 'id'), required(args, 'step'), revision(args));
+    }
+    if (noun === 'task' && action === 'step-review-record') {
+        return workflow.recordExternalStepReview(repo, required(args, 'id'), required(args, 'step'), revision(args), jsonFile(args), required(args, 'actor'), option(args, 'writer-token') ?? null);
+    }
     if (noun === 'task' && action === 'corrective-decision-recover') {
         return workflow.recoverStepCorrectiveDecision(repo, required(args, 'id'), required(args, 'step'), revision(args), required(args, 'actor'), option(args, 'writer-token') ?? null);
     }
     if (noun === 'task' && action === 'remediation-mode-recover') {
         return workflow.recoverRemediationMode(repo, required(args, 'id'), required(args, 'step'), revision(args), required(args, 'actor'), option(args, 'writer-token') ?? null);
     }
+    if (noun === 'task' && action === 'plan-integrity-recover') {
+        return workflow.recoverPlanIntegrity(repo, required(args, 'id'), required(args, 'step'), revision(args), required(args, 'actor'), option(args, 'writer-token') ?? null);
+    }
     if (noun === 'task' && action === 'corrective-decision') {
         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);
+    if (noun === 'task' && action === 'corrective-yield') {
+        return workflow.executeCorrectiveYield(repo, required(args, 'id'), revision(args), required(args, 'actor'), required(args, 'writer-token'), required(args, 'reason'));
+    }
+    if (noun === 'task' && action === 'corrective-yield-recover') {
+        return workflow.recoverCorrectiveYield(repo, required(args, 'id'), required(args, 'transaction-id'));
+    }
+    if (noun === 'task' && action === 'corrective-replan-prepare') {
+        return workflow.prepareCorrectiveReplan(repo, required(args, 'id'), jsonFile(args));
+    }
+    if (noun === 'task' && action === 'corrective-replan-confirm') {
+        return workflow.confirmCorrectiveReplan(repo, required(args, 'id'), jsonFile(args), jsonFile(args, 'gate-file'), required(args, 'confirmation-code'));
+    }
+    if (noun === 'task' && action === 'corrective-replan-execute') {
+        return workflow.executeCorrectiveReplan(repo, required(args, 'id'), jsonFile(args), jsonFile(args, 'credential-file'));
+    }
+    if (noun === 'task' && action === 'corrective-replan-recover') {
+        return workflow.recoverCorrectiveReplan(repo, required(args, 'id'), required(args, 'transaction-id'));
+    }
+    if (noun === 'task' && (action === 'handoff' || action === 'handoff-prepare' || action === 'handoff-replace')) {
+        const replacePending = action === 'handoff-replace';
+        const outcome = workflow.handoffTask(repo, required(args, 'id'), revision(args), required(args, 'actor'), replacePending
+            ? required(args, 'target-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, replacePending);
+        const { claimToken, ...bundle } = outcome.bundle;
+        return {
+            credentialHandoff: {
+                token: claimToken,
+                kind: 'claim-token',
+                targetActor: outcome.bundle.delegate,
+                action: 'task claim',
+                option: '--claim-token',
+                source: replacePending ? 'task handoff-replace' : '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);
+        return {
+            writerCredential: { disposition: outcome.writerCredential.disposition },
+            ...(outcome.writerCredential.disposition === 'issued' ? {
+                writerLeaseReceipt: {
+                    token: outcome.writerCredential.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: outcome.lease,
+        };
+    }
+    if (noun === 'task' && action === 'writer-credential-replace') {
+        const outcome = workflow.replaceClaimedWriterCredential(repo, required(args, 'id'), revision(args), required(args, 'actor'));
+        return {
+            writerCredential: { disposition: outcome.writerCredential.disposition },
+            writerLeaseReceipt: {
+                token: outcome.writerCredential.token,
+                kind: 'writer-lease',
+                source: 'task writer-credential-replace',
+                sensitive: true,
+                oneTime: false,
+            },
+            task: outcome.task,
+            lease: outcome.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'
@@ -421,8 +797,11 @@ async function dispatch(args) {
         return workflow.confirmExternalMerge(repo, required(args, 'id'), revision(args), required(args, 'writer-token'), option(args, 'actor'));
     }
     if (noun === 'milestone' && action === 'show') {
-        const context = workflow.context(repo);
-        return context.store.readMilestone(context.identity.projectId, required(args, 'id'));
+        const identity = resolveRepositoryIdentity(repo);
+        return workflow.store.readMilestone(identity.projectId, required(args, 'id'));
+    }
+    if (noun === 'milestone' && action === 'progress') {
+        return workflow.milestoneProgress(repo, required(args, 'id'));
     }
     if (noun === 'milestone' && action === 'plan-set') {
         return workflow.setMilestonePlan(repo, required(args, 'id'), revision(args), jsonFile(args));
@@ -455,39 +834,100 @@ async function dispatch(args) {
         return workflow.cancelMilestone(repo, required(args, 'id'), revision(args), required(args, 'reason'));
     }
     if (noun === 'locks' && (action === 'inspect' || action === 'repair')) {
-        const context = workflow.context(repo);
         const id = required(args, '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;
+        if (action === 'repair')
+            return workflow.repairStaleWriterLease(repo, id);
+        const inspection = workflow.inspectWriterLease(repo, id);
+        return inspection ? { ...inspection, repaired: false } : null;
     }
     throw new WorkflowError('INVALID_ARGUMENT', 'Unknown command.', {
         command: args.positionals.join(' '),
         hint: 'Use doctor, status, next, update preflight, state <action>, delegation <action>, project-memory <action>, discovery <action>, task <action>, milestone <action>, or locks <action>.',
     });
 }
+function credentialAllowancesForResult(args, value) {
+    const [noun, action] = args.positionals;
+    if (!isRecord(value))
+        return [];
+    if (noun === 'task' && (action === 'run' || action === 'claim' || action === 'writer-credential-replace')) {
+        const disposition = isRecord(value.writerCredential) ? value.writerCredential.disposition : null;
+        const receipt = isRecord(value.writerLeaseReceipt) ? value.writerLeaseReceipt : null;
+        if (disposition === 'issued'
+            && receipt?.kind === 'writer-lease'
+            && receipt.source === `task ${action}`
+            && receipt.sensitive === true) {
+            return [{ path: '$.writerLeaseReceipt.token' }];
+        }
+        return [];
+    }
+    if (noun === 'task' && (action === 'handoff' || action === 'handoff-prepare' || action === 'handoff-replace')) {
+        const receipt = isRecord(value.credentialHandoff) ? value.credentialHandoff : null;
+        if (receipt?.kind === 'claim-token'
+            && receipt.source === (action === 'handoff-replace' ? 'task handoff-replace' : 'task handoff-prepare')
+            && receipt.sensitive === true
+            && receipt.oneTime === true) {
+            return [{ path: '$.credentialHandoff.token' }];
+        }
+    }
+    return [];
+}
+function rawCredentialInputs(argv) {
+    const values = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        for (const optionName of ['--writer-token', '--claim-token', '--confirmation-code']) {
+            if (argument === optionName && argv[index + 1])
+                values.push(argv[index + 1]);
+            if (argument.startsWith(`${optionName}=`))
+                values.push(argument.slice(optionName.length + 1));
+        }
+    }
+    return [...new Set(values.filter(Boolean))];
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
 async function main() {
+    const argv = process.argv.slice(2);
+    const sensitiveInputs = rawCredentialInputs(argv);
     try {
-        const value = await dispatch(parseArguments(process.argv.slice(2)));
+        const args = parseArguments(argv);
+        const value = await dispatch(args);
+        assertCliSuccessCredentialSafety(value, credentialAllowancesForResult(args, value), sensitiveInputs);
         process.stdout.write(`${JSON.stringify({ ok: true, value }, null, 2)}\n`);
     }
     catch (error) {
+        if (error instanceof UnsafeCredentialOutputError) {
+            process.stderr.write(`${JSON.stringify({
+                ok: false,
+                error: {
+                    code: 'STATE_CORRUPT',
+                    message: error.message,
+                    details: { credentialPaths: error.paths },
+                },
+            }, null, 2)}\n`);
+            process.exitCode = 2;
+            return;
+        }
         if (error instanceof WorkflowError) {
-            process.stderr.write(`${JSON.stringify({ ok: false, error: { code: error.code, message: error.message, details: error.details } }, null, 2)}\n`);
+            process.stderr.write(`${JSON.stringify({
+                ok: false,
+                error: {
+                    code: error.code,
+                    message: projectCliErrorMessage(error.message, sensitiveInputs),
+                    details: projectCliErrorValue(error.details, sensitiveInputs),
+                },
+            }, null, 2)}\n`);
             process.exitCode = 2;
             return;
         }
-        process.stderr.write(`${JSON.stringify({ ok: false, error: { code: 'UNEXPECTED', message: error instanceof Error ? error.message : String(error) } }, null, 2)}\n`);
+        process.stderr.write(`${JSON.stringify({
+            ok: false,
+            error: {
+                code: 'UNEXPECTED',
+                message: projectCliErrorMessage(error instanceof Error ? error.message : String(error), sensitiveInputs),
+            },
+        }, null, 2)}\n`);
         process.exitCode = 1;
     }
 }