@software-dlc/cli 0.157.2

package/dist/local/workspace-cli.js

@@ -0,0 +1,1524 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { createDocumentNode, documentOutlineForNode, exportDocumentNode, linkDocumentNode, loadDocumentOutline, readDocumentNodeBounded, updateDocumentNode } from './document-commands.js';
+import { parseFileList } from './blast-radius.js';
+import { createGuide, exportGuide, listGuides, parseGuideExport, updateGuide, validateGuide } from './guide-commands.js';
+import { linkJourneyTest, listJourneys, showJourney } from './journey-commands.js';
+import { importTestNodes, linkTestCriterion, linkTestNode } from './test-commands.js';
+import { LocalWorkspaceRuntime } from './workspace-runtime.js';
+import { checkGraphAdmission } from './workspace-admission.js';
+import { parseClaimView } from './workspace-claim-views.js';
+import { gitClaimStatusReader, parseClaimStatus, parseClaimStatusEnvironment, parseClaimStatusView } from './workspace-claim-status.js';
+import { parseSourcesFile, sourceReferenceFailures } from './workspace-evidence.js';
+import { checkSources, coverageSources, gitCoverageReader, limitProblem, lookupSources, ofRepository, parseLookupTarget } from './workspace-sources.js';
+import { integrationBranch, repositoryNames } from './git.js';
+import { local_workspace_task_scope_schema } from './workspace-scope.js';
+import { formatVariantsReport } from './variants.js';
+import { startLocalWorkspaceViewer } from './workspace-viewer-server.js';
+import { appShellReader } from './app-shell-readers.js';
+import { worktreesProvider } from './app-worktrees.js';
+import { loadViewModule, viewerProviders } from '../view-seam.js';
+import { localEnvironmentRemoteConfiguration } from './workspace-remote-provider.js';
+import { applyWorkspaceStorageRelocation, cloneWorkspaceStorage, exportWorkspaceStorage, inspectWorkspaceTopology, planWorkspaceStorageRelocation, recoverWorkspaceStorageRelocation } from './workspace-topology-runtime.js';
+import { LOCAL_WORKSPACE_STORAGE_MODES } from './workspace-topology.js';
+function argumentValue(args, name) {
+    const index = args.indexOf(name);
+    if (index >= 0)
+        return args[index + 1] ?? null;
+    const inline = args.find((argument) => argument.startsWith(`${name}=`));
+    return inline ? inline.slice(name.length + 1) : null;
+}
+function requiredArgument(args, name) {
+    const value = argumentValue(args, name);
+    if (!value)
+        throw new Error(`Missing required ${name} value.`);
+    return value;
+}
+function hasFlag(args, name) {
+    return args.includes(name);
+}
+/** Every value of a repeatable argument, in order. */
+function argumentValues(args, name) {
+    const values = [];
+    args.forEach((argument, index) => {
+        if (argument === name && args[index + 1] !== undefined) {
+            values.push(args[index + 1]);
+        }
+        else if (argument.startsWith(`${name}=`)) {
+            values.push(argument.slice(name.length + 1));
+        }
+    });
+    return values;
+}
+/** The gate a commit is queued under; a landing when `--gate` is left out. */
+function gateArgument(args) {
+    const gate = argumentValue(args, '--gate');
+    if (gate === null)
+        return undefined;
+    if (gate === 'plan' || gate === 'design')
+        return gate;
+    throw new Error(`Unknown gate ${gate}: use plan or design.`);
+}
+async function taskScopeArgument(args) {
+    const scope_file = resolve(requiredArgument(args, '--scope-file'));
+    const input = JSON.parse(await readFile(scope_file, 'utf8'));
+    return local_workspace_task_scope_schema.parse(input);
+}
+async function jsonFileArgument(args, name) {
+    const file_path = resolve(requiredArgument(args, name));
+    return JSON.parse(await readFile(file_path, 'utf8'));
+}
+function currentWorkspaceId(runtime) {
+    const workspace = runtime.store.getWorkspaceByGitWorktreePath(runtime.git.repository_root);
+    if (!workspace || workspace.status !== 'active') {
+        throw new Error('The current Git worktree is not an active local workspace. Run sdlc workspace init first.');
+    }
+    return workspace.id;
+}
+const FIND_USAGE = 'Usage: sdlc workspace find <term>... [--type <type>[,<type>]] [--origin built|shelf] [--limit <n>] [--workspace <workspace-id>] [--view <view>]';
+const SHOW_USAGE = 'Usage: sdlc workspace show <id>... [--budget <chars>] [--full] [--workspace <workspace-id>] [--view <view>]';
+/** The flags of find and show that take a value, the global ones included, so no value is read as a term or id. */
+const READ_VALUE_FLAGS = [
+    '--type',
+    '--origin',
+    '--limit',
+    '--budget',
+    '--workspace',
+    '--view',
+    '--repository-state-dir',
+    '--graph-repository-id'
+];
+/** The arguments before `--`, the only ones find and show read flags from. */
+function optionArguments(args) {
+    const end = args.indexOf('--');
+    return end < 0 ? args : args.slice(0, end);
+}
+/**
+ * The terms or ids of a find or show argument list. Refuses, with `usage`, a
+ * flag the command does not read, a value flag with no value, or a switch
+ * written with a value, rather than reading them as words. After `--`, every
+ * argument is a word, so a term may start with dashes.
+ */
+function readArguments(args, switches, usage) {
+    const out = [];
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (argument === '--') {
+            out.push(...args.slice(index + 1));
+            break;
+        }
+        if (!argument.startsWith('--')) {
+            out.push(argument);
+        }
+        else if (READ_VALUE_FLAGS.some((flag) => argument.startsWith(`${flag}=`))) {
+            continue;
+        }
+        else if (READ_VALUE_FLAGS.includes(argument)) {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new Error(`${argument} needs a value. ${usage}`);
+            }
+            index++;
+        }
+        else if (!switches.includes(argument)) {
+            throw new Error(`Unknown flag ${argument}. ${usage}`);
+        }
+    }
+    return out;
+}
+function positiveInteger(value, name) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`${name} takes a positive whole number, not ${value}.`);
+    }
+    return parsed;
+}
+function workspaceArgument(runtime, args, name = '--workspace') {
+    return argumentValue(args, name) ?? currentWorkspaceId(runtime);
+}
+function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+/**
+ * The line `sdlc viewer` prints once it listens. The viewer makes no graph mutation. It writes
+ * view state, the pins, named in view_writes when the Threads panel can pin, and coordination
+ * records named in coordination_writes when the engine has them: the user's Done on a task (status
+ * user-done), and the Worktrees page's Merge (promote join main) and Remove (archive.py worktrees
+ * --apply --only). page says which page answers the url: the React viewer, or the classic page when
+ * no bundle is built.
+ */
+export function viewerStartLine(url, pins, page, userDone = false, worktrees = false) {
+    return {
+        version: 1,
+        status: 'listening',
+        url,
+        binding: 'loopback',
+        mutations: 'unavailable',
+        view_writes: pins ? ['pins'] : [],
+        coordination_writes: [...(userDone ? ['user-done'] : []), ...(worktrees ? ['worktree-merge', 'worktree-remove'] : [])],
+        ...(page === 'classic'
+            ? {
+                page,
+                note: 'The React viewer is not built here (pnpm --dir packages/viewer-web build); serving the classic page.'
+            }
+            : page
+                ? { page, classic: `${url}classic/` }
+                : {})
+    };
+}
+async function readStream(stream) {
+    let text = '';
+    for await (const chunk of stream)
+        text += String(chunk);
+    return text;
+}
+function actorArgument(args) {
+    const actor = argumentValue(args, '--actor');
+    if (actor === null)
+        return undefined;
+    if (actor !== 'human' && actor !== 'ai') {
+        throw new Error('--actor must be human or ai.');
+    }
+    return actor;
+}
+function storageModeArgument(args, required = false) {
+    const mode = argumentValue(args, '--storage-mode');
+    if (mode === null) {
+        if (required)
+            throw new Error('Missing required --storage-mode value.');
+        return undefined;
+    }
+    if (!LOCAL_WORKSPACE_STORAGE_MODES.includes(mode)) {
+        throw new Error('--storage-mode must be machine_shared or self_contained.');
+    }
+    return mode;
+}
+async function resolverArguments(runtime, args) {
+    const resolve_conflicts = hasFlag(args, '--resolve-conflicts');
+    const allow_network_resolver = hasFlag(args, '--allow-network-resolver');
+    if (!resolve_conflicts) {
+        if (allow_network_resolver) {
+            throw new Error('--allow-network-resolver requires --resolve-conflicts.');
+        }
+        return {};
+    }
+    const loaded = await runtime.loadResolver({
+        actor_workspace_id: currentWorkspaceId(runtime),
+        allow_network_resolver
+    });
+    return {
+        conflict_resolver: loaded.resolver,
+        resolution_budget: loaded.budget,
+        allow_network_resolver
+    };
+}
+export function isLocalWorkspaceCommand(command, subcommand) {
+    return (!(command === 'branch' &&
+        (subcommand === 'bind' ||
+            subcommand === 'commit' ||
+            subcommand === 'apply')) &&
+        (command === 'workspace' ||
+            command === 'topology' ||
+            command === 'integrate' ||
+            command === 'handoff' ||
+            command === 'resolver' ||
+            command === 'portable' ||
+            command === 'branch' ||
+            command === 'merge' ||
+            command === 'viewer' ||
+            command === 'variants' ||
+            command === 'remote'));
+}
+async function runEnvironmentCommand(runtime, input) {
+    const actor_workspace_id = currentWorkspaceId(runtime);
+    const key = `${input.command}:${input.subcommand ?? ''}`;
+    if (key === 'remote:set') {
+        const credential_variable = argumentValue(input.args, '--credential-env');
+        const local_defaults = hasFlag(input.args, '--local');
+        if (local_defaults && credential_variable !== null) {
+            throw new Error('--local always uses SDLC_LOCAL_API_KEY and does not accept --credential-env.');
+        }
+        const remote = local_defaults
+            ? localEnvironmentRemoteConfiguration({
+                name: argumentValue(input.args, '--name') ?? undefined,
+                url: argumentValue(input.args, '--url') ?? undefined,
+                project_id: argumentValue(input.args, '--project-id') ?? undefined
+            })
+            : {
+                name: requiredArgument(input.args, '--name'),
+                url: requiredArgument(input.args, '--url'),
+                association: {
+                    kind: 'project',
+                    project_id: requiredArgument(input.args, '--project-id')
+                },
+                credential: credential_variable === null
+                    ? null
+                    : { kind: 'environment', variable: credential_variable }
+            };
+        printJson(await runtime.setRemote({
+            actor_workspace_id,
+            remote
+        }));
+    }
+    else if (key === 'remote:list') {
+        printJson({ version: 1, remotes: await runtime.listRemotes() });
+    }
+    else if (key === 'remote:inspect') {
+        printJson(await runtime.inspectRemote(requiredArgument(input.args, '--name')));
+    }
+    else if (key === 'remote:remove') {
+        printJson(await runtime.removeRemote({
+            actor_workspace_id,
+            name: requiredArgument(input.args, '--name')
+        }));
+    }
+    else if (key === 'remote:discover' || key === 'remote:fetch') {
+        const timeout_value = argumentValue(input.args, '--timeout-ms');
+        const common = {
+            actor_workspace_id,
+            name: requiredArgument(input.args, '--name'),
+            timeout_ms: timeout_value === null ? undefined : Number(timeout_value)
+        };
+        printJson(key === 'remote:discover'
+            ? await runtime.discoverRemote(common)
+            : await runtime.fetchRemote({
+                ...common,
+                source_ref: requiredArgument(input.args, '--ref')
+            }));
+    }
+    else if (key === 'remote:refs') {
+        printJson({
+            version: 1,
+            refs: runtime.listRemoteTrackingRefs(argumentValue(input.args, '--name') ?? undefined)
+        });
+    }
+    else if (key === 'remote:push') {
+        const timeout_value = argumentValue(input.args, '--timeout-ms');
+        printJson(await runtime.pushRemote({
+            actor_workspace_id,
+            name: requiredArgument(input.args, '--name'),
+            destination_ref: requiredArgument(input.args, '--ref'),
+            new_commit_id: argumentValue(input.args, '--commit') ?? undefined,
+            timeout_ms: timeout_value === null ? undefined : Number(timeout_value)
+        }));
+    }
+    else if (key === 'remote:push-journals') {
+        printJson({
+            version: 1,
+            journals: runtime.listRemotePushJournals(argumentValue(input.args, '--name') ?? undefined)
+        });
+    }
+    else if (key === 'remote:topic') {
+        const timeout_value = argumentValue(input.args, '--timeout-ms');
+        printJson(await runtime.publishRemoteTopic({
+            actor_workspace_id,
+            name: requiredArgument(input.args, '--name'),
+            topic_ref: requiredArgument(input.args, '--ref'),
+            target_ref: requiredArgument(input.args, '--target-ref'),
+            new_commit_id: argumentValue(input.args, '--commit') ?? undefined,
+            timeout_ms: timeout_value === null ? undefined : Number(timeout_value)
+        }));
+    }
+    else if (key === 'remote:topic-journals') {
+        printJson({
+            version: 1,
+            journals: runtime.listRemoteTopicJournals(argumentValue(input.args, '--name') ?? undefined)
+        });
+    }
+    else if (key === 'remote:pr') {
+        const timeout_value = argumentValue(input.args, '--timeout-ms');
+        printJson(await runtime.createRemotePullRequest({
+            actor_workspace_id,
+            name: requiredArgument(input.args, '--name'),
+            source_ref: requiredArgument(input.args, '--source-ref'),
+            target_ref: requiredArgument(input.args, '--target-ref'),
+            title: requiredArgument(input.args, '--title'),
+            description: argumentValue(input.args, '--description'),
+            timeout_ms: timeout_value === null ? undefined : Number(timeout_value)
+        }));
+    }
+    else if (key === 'remote:pr-journals') {
+        printJson({
+            version: 1,
+            journals: runtime.listRemotePullRequestJournals(argumentValue(input.args, '--name') ?? undefined)
+        });
+    }
+    else if (key === 'portable:plan') {
+        printJson(await runtime.planPortableHistory({
+            actor_workspace_id,
+            local_commit_id: argumentValue(input.args, '--commit') ?? undefined
+        }));
+    }
+    else if (key === 'portable:convert') {
+        const identity_file = argumentValue(input.args, '--identity-file');
+        printJson(await runtime.convertPortableHistory({
+            actor_workspace_id,
+            local_commit_id: argumentValue(input.args, '--commit') ?? undefined,
+            identity_file: identity_file === null
+                ? undefined
+                : await jsonFileArgument(input.args, '--identity-file'),
+            base_remote_name: argumentValue(input.args, '--base-remote') ?? undefined,
+            base_source_ref: argumentValue(input.args, '--base-ref') ?? undefined
+        }));
+    }
+    else if (key === 'branch:list') {
+        printJson({ version: 1, branches: runtime.listLocalBranches() });
+    }
+    else if (key === 'branch:create') {
+        printJson(await runtime.createLocalBranchFromTrackingRef({
+            actor_workspace_id,
+            local_ref: requiredArgument(input.args, '--ref'),
+            remote_name: requiredArgument(input.args, '--from-remote'),
+            source_ref: requiredArgument(input.args, '--from-ref')
+        }));
+    }
+    else if (key === 'branch:select') {
+        printJson(await runtime.selectLocalBranch({ actor_workspace_id }));
+    }
+    else if (key === 'merge:upstream') {
+        const result = await runtime.integrateBranchUpstream({
+            actor_workspace_id,
+            ...(await resolverArguments(runtime, input.args))
+        });
+        printJson(result);
+        if (result.status !== 'already_integrated' &&
+            result.status !== 'fast_forwarded' &&
+            result.status !== 'merged') {
+            process.exitCode = 2;
+        }
+    }
+    else if (key === 'merge:status') {
+        printJson(await runtime.inspectBranchUpstream({ actor_workspace_id }));
+    }
+    else if (key === 'merge:revert') {
+        const result = await runtime.revertBranchUpstream({
+            actor_workspace_id,
+            branch_integration_attempt_id: requiredArgument(input.args, '--attempt'),
+            message: argumentValue(input.args, '--message') ?? undefined
+        });
+        printJson(result);
+        if (result.status !== 'reverted')
+            process.exitCode = 2;
+    }
+    else if (key === 'merge:attempts') {
+        printJson({
+            version: 1,
+            attempts: runtime.listBranchIntegrationAttempts(argumentValue(input.args, '--ref') ?? undefined)
+        });
+    }
+    else if (key === 'merge:resolution-attempts') {
+        printJson({
+            version: 1,
+            attempts: runtime.listBranchIntegrationResolutionAttempts(requiredArgument(input.args, '--attempt'))
+        });
+    }
+    else if (key === 'merge:reverts') {
+        printJson({
+            version: 1,
+            attempts: runtime.listBranchIntegrationRevertAttempts(argumentValue(input.args, '--ref') ?? undefined)
+        });
+    }
+    else if (key === 'resolver:configure') {
+        printJson(await runtime.configureResolverFromFile({
+            actor_workspace_id,
+            path: requiredArgument(input.args, '--file')
+        }));
+    }
+    else if (key === 'resolver:status') {
+        printJson(await runtime.resolverStatus());
+    }
+    else if (key === 'resolver:clear') {
+        printJson(await runtime.clearResolver({ actor_workspace_id }));
+    }
+    else {
+        return false;
+    }
+    return true;
+}
+const DOCUMENT_USAGE = 'Usage: sdlc workspace doc new [<uuid>] --outline <file> | update <node> --outline <file> | outline <node> [--output <file>] | export <node> | read <node> --outline|--section <block>|--search <text> [--max-results <n>] | link <node> --describes <node> [--id <uuid>] [--description <text>]';
+/**
+ * `sdlc workspace doc`: Document nodes in the current workspace's
+ * projection, under the workspace's authority check and operation lock.
+ */
+async function runDocumentCommand(runtime, args) {
+    const [action, positional] = args;
+    return runtime.withDocumentProjection({
+        actor_workspace_id: currentWorkspaceId(runtime),
+        operation: action ?? 'doc',
+        run: (projection_dir) => documentCommand(projection_dir, action, positional, args)
+    });
+}
+async function documentCommand(projection_dir, action, positional, args) {
+    const node_id = positional && !positional.startsWith('--') ? positional : null;
+    const requiredNode = () => {
+        if (!node_id)
+            throw new Error(DOCUMENT_USAGE);
+        return node_id;
+    };
+    const outlineFile = () => loadDocumentOutline(resolve(requiredArgument(args, '--outline')));
+    switch (action) {
+        case 'new': {
+            // The node id may be given like every other doc command, or as --id.
+            const flag_id = argumentValue(args, '--id');
+            if (node_id && flag_id && node_id !== flag_id) {
+                throw new Error(`Two node ids given: ${node_id} and --id ${flag_id}.`);
+            }
+            return createDocumentNode({
+                projection_dir,
+                outline: await outlineFile(),
+                node_id: node_id ?? flag_id ?? undefined
+            });
+        }
+        case 'update':
+            return updateDocumentNode({
+                projection_dir,
+                node_id: requiredNode(),
+                outline: await outlineFile()
+            });
+        case 'outline': {
+            const outline = await documentOutlineForNode(projection_dir, requiredNode());
+            const output = argumentValue(args, '--output');
+            if (!output)
+                return outline;
+            await writeFile(resolve(output), `${JSON.stringify(outline, null, 2)}\n`);
+            return {
+                version: 1,
+                status: 'written',
+                path: resolve(output),
+                source_hash: outline.source_hash
+            };
+        }
+        case 'export':
+            return exportDocumentNode(projection_dir, requiredNode());
+        case 'read': {
+            const section = argumentValue(args, '--section');
+            const search = argumentValue(args, '--search');
+            const max_results = argumentValue(args, '--max-results');
+            const request = hasFlag(args, '--outline')
+                ? { read: 'outline' }
+                : section !== null
+                    ? { read: 'section', heading_id: section }
+                    : search !== null
+                        ? {
+                            read: 'search',
+                            query: search,
+                            ...(max_results !== null
+                                ? { max_results: Number(max_results) }
+                                : {})
+                        }
+                        : null;
+            if (!request)
+                throw new Error(DOCUMENT_USAGE);
+            return readDocumentNodeBounded(projection_dir, requiredNode(), request);
+        }
+        case 'link':
+            return linkDocumentNode({
+                projection_dir,
+                node_id: requiredNode(),
+                target_id: requiredArgument(args, '--describes'),
+                edge_id: argumentValue(args, '--id') ?? undefined,
+                description: argumentValue(args, '--description') ?? undefined
+            });
+        default:
+            throw new Error(DOCUMENT_USAGE);
+    }
+}
+const DECISION_USAGE = 'Usage: sdlc workspace decision open --question <text> --criterion <text>... [--evaluation <text>...] --decider <who> [--base <commit>] | list | show <decision> | attach <decision> --workspace <id> [--label <text>] | detach <decision> --workspace <id> --reason <text> | digest <decision> --winner <workspace> [--part <workspace>@<pick receipt>=<entity>[,<entity>...]...] | select <decision> --winner <workspace> [--part ...] --digest <sha256> --reason <text> | close <decision> --reason <text> | abandon <decision> --reason <text> | reopen <decision> --reason <text> [--candidate <closed workspace> --path <new worktree>]';
+/**
+ * `--part <workspace>@<receipt>=<kind>:<id>,<kind>:<id>` names entities the
+ * winner picked from another candidate, and the receipt of that pick.
+ */
+function decisionParts(args) {
+    return argumentValues(args, '--part').map((value) => {
+        const separator = value.indexOf('=');
+        const receipt = value.lastIndexOf('@', separator);
+        if (receipt <= 0 || separator <= receipt + 1) {
+            throw new Error(DECISION_USAGE);
+        }
+        return {
+            candidate_workspace_id: value.slice(0, receipt),
+            pick_receipt_id: value.slice(receipt + 1, separator),
+            entities: value
+                .slice(separator + 1)
+                .split(',')
+                .map((entity) => entity.trim())
+                .filter(Boolean)
+        };
+    });
+}
+const PICK_USAGE = 'Usage: sdlc workspace pick --from <workspace> [--commit <id>] --entity <kind>:<id>... [--with-dependencies] [--dry-run] [--message <text>] [--workspace <id>] | pick list [--workspace <id>] | pick show <receipt>';
+const PICK_ENTITY_KINDS = ['node', 'edge', 'path', 'path_relation'];
+/** `--entity <kind>:<id>`, repeatable. */
+function pickEntities(args) {
+    return argumentValues(args, '--entity').map((value) => {
+        const separator = value.indexOf(':');
+        const entity_kind = PICK_ENTITY_KINDS.find((kind) => kind === value.slice(0, separator));
+        const entity_id = value.slice(separator + 1);
+        if (separator < 1 || !entity_kind || !entity_id) {
+            throw new Error(`--entity is <kind>:<id> with kind ${PICK_ENTITY_KINDS.join(', ')}; got ${value}.`);
+        }
+        return { entity_kind, entity_id };
+    });
+}
+const PICK_VALUE_FLAGS = [
+    '--from',
+    '--commit',
+    '--entity',
+    '--message',
+    '--workspace',
+    '--repository-state-dir',
+    '--graph-repository-id'
+];
+const PICK_SWITCHES = ['--with-dependencies', '--dry-run'];
+/**
+ * Rejects a pick argument list that would otherwise be read wrongly: a value
+ * flag with no value or with another flag as its value, an unknown flag, or a
+ * stray word. A value that starts with `--` is written `--flag=value`.
+ */
+function assertPickArguments(args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (PICK_SWITCHES.includes(argument))
+            continue;
+        if (PICK_VALUE_FLAGS.some((flag) => argument.startsWith(`${flag}=`))) {
+            continue;
+        }
+        const value = args[index + 1];
+        if (!PICK_VALUE_FLAGS.includes(argument) ||
+            value === undefined ||
+            value.startsWith('--')) {
+            throw new Error(PICK_USAGE);
+        }
+        index += 1;
+    }
+}
+/**
+ * `sdlc workspace pick`: copy chosen entities from another workspace
+ * (docs/specs/local-ai-multi-worktree-integration.md, Pick).
+ */
+async function runPickCommand(runtime, args) {
+    const [action, positional] = args;
+    if (action === 'list') {
+        return {
+            version: 1,
+            receipts: runtime.store.picks.listReceipts(workspaceArgument(runtime, args))
+        };
+    }
+    if (action === 'show') {
+        if (!positional || positional.startsWith('--'))
+            throw new Error(PICK_USAGE);
+        return runtime.store.picks.getReceipt(positional);
+    }
+    assertPickArguments(args);
+    const result = await runtime.pickEntities({
+        actor_workspace_id: workspaceArgument(runtime, args),
+        source_workspace_id: requiredArgument(args, '--from'),
+        source_commit_id: argumentValue(args, '--commit') ?? undefined,
+        selection: pickEntities(args),
+        with_dependencies: hasFlag(args, '--with-dependencies'),
+        dry_run: hasFlag(args, '--dry-run'),
+        message: argumentValue(args, '--message') ?? undefined
+    });
+    if (result.status.startsWith('blocked_') ||
+        result.status === 'picked_recovery_required') {
+        process.exitCode = 2;
+    }
+    return result;
+}
+/**
+ * `sdlc workspace decision`: local Decisions over candidate plan workspaces
+ * (docs/specs/graph-variants.md, Decisions, Local first). The only writer of
+ * Decision records.
+ */
+async function runDecisionCommand(runtime, args) {
+    const [action, positional] = args;
+    const decisions = runtime.store.decisions;
+    const actor = await runtime.decisionActor();
+    const decision_id = () => {
+        if (!positional || positional.startsWith('--')) {
+            throw new Error(DECISION_USAGE);
+        }
+        return positional;
+    };
+    const selection = () => ({
+        decision_id: decision_id(),
+        winner_workspace_id: requiredArgument(args, '--winner'),
+        parts: decisionParts(args)
+    });
+    switch (action) {
+        case 'open':
+            return decisions.openDecision({
+                actor_workspace_id: actor.id,
+                question: requiredArgument(args, '--question'),
+                criteria: argumentValues(args, '--criterion'),
+                evaluations: argumentValues(args, '--evaluation'),
+                decider: requiredArgument(args, '--decider'),
+                base_commit_id: argumentValue(args, '--base') ?? undefined
+            });
+        case 'list':
+            return { version: 1, decisions: decisions.listDecisions() };
+        case 'show':
+            return decisions.getDecision(decision_id());
+        case 'attach':
+            return decisions.attachCandidate({
+                decision_id: decision_id(),
+                workspace_id: requiredArgument(args, '--workspace'),
+                label: argumentValue(args, '--label') ?? undefined
+            });
+        case 'detach':
+            return decisions.detachCandidate({
+                decision_id: decision_id(),
+                workspace_id: requiredArgument(args, '--workspace'),
+                reason: requiredArgument(args, '--reason')
+            });
+        case 'digest':
+            return decisions.selectionDigest(selection());
+        case 'select':
+            return decisions.select({
+                ...selection(),
+                digest: requiredArgument(args, '--digest'),
+                reason: requiredArgument(args, '--reason')
+            });
+        case 'close':
+            return decisions.closeDecision({
+                decision_id: decision_id(),
+                reason: requiredArgument(args, '--reason')
+            });
+        case 'abandon':
+            return decisions.abandon({
+                decision_id: decision_id(),
+                reason: requiredArgument(args, '--reason')
+            });
+        case 'reopen':
+            return runtime.reopenDecision({
+                decision_id: decision_id(),
+                reason: requiredArgument(args, '--reason'),
+                revive_workspace_id: argumentValue(args, '--candidate') ?? undefined,
+                target_path: argumentValue(args, '--path') ?? undefined
+            });
+        default:
+            throw new Error(DECISION_USAGE);
+    }
+}
+const TEST_USAGE = 'Usage: sdlc workspace test import [--parent <feature or story>] [--dry-run] | link <test> --verifies <node> [--id <uuid>] | link <test> --criterion <node>#<criterion> [--id <uuid>] | link <test> --journey <entry story> [--via <story,...>]';
+const JOURNEY_USAGE = 'Usage: sdlc workspace journey list | show <entry story>';
+const GUIDE_USAGE = 'Usage: sdlc workspace guide create --journey <entry story> --label <title> [--description <summary>] [--id <uuid>] | export <guide> [--output <file>] | update <guide> --file <file> | validate <guide> | list';
+const ADMISSION_USAGE = 'Usage: sdlc workspace admission show | record --origin <origin> [--capability <name>]... --evidence <text> | check --graph-file <file>';
+/**
+ * `sdlc workspace admission`: the repository's vocabulary admission record
+ * (Local Vocabulary Admission Gate). promote publish records what its origin
+ * advertised and checks its export before saving; check exits 1 when the
+ * graph holds an item the record does not admit.
+ */
+async function runAdmissionCommand(runtime, args) {
+    const [action] = args;
+    if (action === 'show') {
+        return { version: 1, admission: runtime.store.admissions.get() };
+    }
+    if (action === 'record') {
+        return {
+            version: 1,
+            status: 'recorded',
+            admission: runtime.store.admissions.record({
+                origin: requiredArgument(args, '--origin'),
+                capabilities: argumentValues(args, '--capability'),
+                evidence: requiredArgument(args, '--evidence')
+            })
+        };
+    }
+    if (action === 'check') {
+        const file = requiredArgument(args, '--graph-file');
+        const graph = JSON.parse(await readFile(resolve(file), 'utf8'));
+        if (!Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
+            throw new Error(`${file} is not a graph with nodes and edges.`);
+        }
+        const result = checkGraphAdmission({
+            graph: graph,
+            admission: runtime.store.admissions.get()
+        });
+        if (result.status === 'refused')
+            process.exitCode = 1;
+        return result;
+    }
+    throw new Error(ADMISSION_USAGE);
+}
+const EVIDENCE_USAGE = 'Usage: sdlc workspace evidence status [--behind] [--node <id>]... [--edge <id>]... | verify --sources <file> [--commit <commit>] | sign [--node <id>]... [--edge <id>]... [--changed] [--reference <id>]... [--commit <commit>] [--repository <dir>] | record --sources <file> [--commit <commit>] [--sign] | lookup <path>[:<line>]|<directory>/ [--symbol <name>] | check [--commit <commit>] | coverage [--commit <commit>] [--under <dir>] [--files]\n' +
+    'Every evidence command but verify takes --graph <dir>, the worktree of the local workspace whose graph it writes or reads (default: here); record, lookup, check and coverage take --repository <dir>, the Git repository whose code the references cite (default: here). check and coverage default --commit to the integration branch, record to HEAD. lookup, check and coverage read the projection as it stands, with each pending claim at its built content. record exits 4 when some references did not hold and only the rest were recorded, and needs a remote that names <owner>/<name> (the tracked remote, else origin): references name their repository by it.';
+/** The flags of the evidence readers that take a value. */
+const EVIDENCE_VALUE_FLAGS = [
+    '--symbol',
+    '--commit',
+    '--under',
+    '--repository',
+    '--graph',
+    '--repository-state-dir',
+    '--graph-repository-id'
+];
+/** The first argument that is neither a flag nor a value flag's value: lookup's target. */
+function evidenceTarget(args) {
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (EVIDENCE_VALUE_FLAGS.includes(argument))
+            index++;
+        else if (!argument.startsWith('--'))
+            return argument;
+    }
+    return null;
+}
+/**
+ * `sdlc workspace evidence record`: a sources file's references, verified at
+ * a commit of --repository by the landing's rule set, written into the
+ * projection of --graph's workspace (sources.py record). The references that
+ * hold are written and the rest listed under not_recorded, with every
+ * reference of a node that would pass 100 references; nothing is written
+ * when none holds. With --sign, exactly those references are signed under the
+ * same workspace lock, or nothing is left written.
+ */
+async function runEvidenceRecord(runtime, args) {
+    const file = requiredArgument(args, '--sources');
+    const nodes = parseSourcesFile(JSON.parse(await readFile(resolve(file), 'utf8')), file);
+    const repository = resolve(argumentValue(args, '--repository') ?? '.');
+    const git = gitClaimStatusReader(repository);
+    const asked = argumentValue(args, '--commit') ?? 'HEAD';
+    const commit = await git.resolve(asked);
+    if (commit === null)
+        throw new Error(`${asked} is not a commit in ${repository}.`);
+    const failures = await sourceReferenceFailures({ git, commit, nodes });
+    const failing = new Set(failures.map((failure) => `${failure.node}\u0000${failure.index}`));
+    const held = {};
+    for (const [node, specs] of Object.entries(nodes)) {
+        const kept = specs.filter((_, index) => !failing.has(`${node}\u0000${index}`));
+        if (kept.length)
+            held[node] = kept;
+    }
+    if (!Object.keys(held).length)
+        throw new Error(`no reference holds, so nothing was recorded: ${failures
+            .map((failure) => `node ${failure.node}: ${failure.problem}`)
+            .join('; ')}`);
+    const { over_limit, ...result } = await runtime.recordSourceReferences({
+        actor_workspace_id: currentWorkspaceId(runtime),
+        nodes: held,
+        commit,
+        repository,
+        sign: hasFlag(args, '--sign')
+    });
+    // A node over the reference limit is left out whole (iss-525), each of its references listed.
+    const too_many = Object.entries(over_limit).map(([node, count]) => ({
+        node,
+        specs: held[node],
+        problem: limitProblem(count, held[node].map((spec) => spec.path))
+    }));
+    if (!result.recorded.length)
+        throw new Error(`no node could be recorded, so nothing was: ${[
+            ...failures.map((failure) => `node ${failure.node}: ${failure.problem}`),
+            ...too_many.map(({ node, problem }) => `node ${node}: ${problem}`)
+        ].join('; ')}`);
+    const not_recorded = [
+        ...failures.map((failure) => ({
+            node: failure.node,
+            ...nodes[failure.node][failure.index],
+            problem: failure.problem
+        })),
+        ...too_many.flatMap(({ node, specs, problem }) => specs.map((spec) => ({ node, ...spec, problem })))
+    ];
+    // 4: the references that hold were written, and the listed ones need fixing.
+    if (not_recorded.length)
+        process.exitCode = 4;
+    return {
+        version: 1,
+        status: not_recorded.length ? 'partial' : 'recorded',
+        commit,
+        ...result,
+        not_recorded,
+        ...(result.signed
+            ? { widened_scope: result.signed.widened_scope ?? [] }
+            : {}),
+        then: 'Run sdlc workspace commit in the graph worktree so blast radius and readiness read the references.'
+    };
+}
+/** `sdlc workspace evidence lookup|check|coverage`: the graph as built read against --repository's code. */
+async function runEvidenceReader(runtime, action, args) {
+    const repository = resolve(argumentValue(args, '--repository') ?? '.');
+    const index = await runtime.workspaceSourceIndex({
+        workspace_id: currentWorkspaceId(runtime)
+    });
+    const entries = ofRepository(index.entries, await repositoryNames(repository));
+    const git = gitClaimStatusReader(repository);
+    const commit = argumentValue(args, '--commit') ?? (await integrationBranch(repository));
+    if (action === 'lookup') {
+        const target = evidenceTarget(args.slice(1));
+        if (!target)
+            throw new Error(EVIDENCE_USAGE);
+        const { path, line } = parseLookupTarget(target);
+        const symbol = argumentValue(args, '--symbol');
+        return {
+            version: 1,
+            status: 'ok',
+            path,
+            line,
+            symbol,
+            matches: lookupSources(entries, path, line, symbol)
+        };
+    }
+    if (action === 'check')
+        return {
+            version: 1,
+            status: 'ok',
+            ...(await checkSources(git, commit, entries, index.nodes))
+        };
+    const { unnamed, ...coverage } = await coverageSources(gitCoverageReader(repository, git), commit, entries, argumentValue(args, '--under') ?? '');
+    return {
+        version: 1,
+        status: 'ok',
+        ...coverage,
+        ...(hasFlag(args, '--files')
+            ? { unnamed }
+            : { unnamed_count: unnamed.length })
+    };
+}
+/**
+ * `sdlc workspace evidence verify`: a sources file's references checked at a
+ * commit by the landing's rule set. It reads Git only, so it runs in any
+ * repository, with or without a local workspace store. Exits 1 when a
+ * reference does not hold.
+ */
+async function runEvidenceVerify(args) {
+    const file = requiredArgument(args, '--sources');
+    const nodes = parseSourcesFile(JSON.parse(await readFile(resolve(file), 'utf8')), file);
+    const git = gitClaimStatusReader(process.cwd());
+    const asked = argumentValue(args, '--commit') ?? 'HEAD';
+    const commit = await git.resolve(asked);
+    if (commit === null)
+        throw new Error(`${asked} is not a commit in this repository.`);
+    const failures = await sourceReferenceFailures({ git, commit, nodes });
+    const problems = failures.map((failure) => `node ${failure.node}: ${failure.problem}`);
+    printJson({
+        version: 1,
+        status: problems.length ? 'refused' : 'holds',
+        commit,
+        problems,
+        // Each reference that does not hold, by its node and place in the node's list.
+        failures
+    });
+    if (problems.length)
+        process.exitCode = 1;
+}
+/** `sdlc workspace evidence status|sign`: claim freshness in, and sign-off of, the current workspace's projection. */
+async function runEvidenceCommand(runtime, args) {
+    const [action] = args;
+    const nodes = argumentValues(args, '--node');
+    const edges = argumentValues(args, '--edge');
+    if (action === 'status') {
+        return runtime.workspaceEvidenceStatus({
+            actor_workspace_id: currentWorkspaceId(runtime),
+            nodes,
+            edges,
+            behind_only: hasFlag(args, '--behind')
+        });
+    }
+    if (action === 'sign') {
+        const references = argumentValues(args, '--reference');
+        const changed = hasFlag(args, '--changed');
+        if (!nodes.length && !edges.length && !references.length && !changed)
+            throw new Error('Name what to sign: --node, --edge, --reference, or --changed.');
+        const result = await runtime.signEvidence({
+            actor_workspace_id: currentWorkspaceId(runtime),
+            nodes,
+            edges,
+            references,
+            changed,
+            commit: argumentValue(args, '--commit') ?? undefined,
+            repository: argumentValue(args, '--repository') ?? undefined
+        });
+        if (result.status === 'refused')
+            process.exitCode = 1;
+        return result;
+    }
+    if (action === 'record')
+        return runEvidenceRecord(runtime, args);
+    if (action === 'lookup' || action === 'check' || action === 'coverage')
+        return runEvidenceReader(runtime, action, args);
+    throw new Error(EVIDENCE_USAGE);
+}
+/** `sdlc workspace journey`: journeys derived in the current workspace's projection. */
+async function runJourneyCommand(runtime, args) {
+    const [action, positional] = args;
+    return runtime.withDocumentProjection({
+        actor_workspace_id: currentWorkspaceId(runtime),
+        operation: `journey-${action ?? 'journey'}`,
+        run: async (projection_dir) => {
+            if (action === 'list')
+                return listJourneys({ projection_dir });
+            if (action === 'show' && positional && !positional.startsWith('--')) {
+                return showJourney({ projection_dir, entry: positional });
+            }
+            throw new Error(JOURNEY_USAGE);
+        }
+    });
+}
+/**
+ * `sdlc workspace guide`: guides in the current workspace's projection
+ * (docs/specs/maintain-guides.md). validate exits 1 when the guide is not
+ * publishable.
+ */
+async function runGuideCommand(runtime, args) {
+    const [action, positional] = args;
+    const node_id = positional && !positional.startsWith('--') ? positional : null;
+    const requiredGuide = () => {
+        if (!node_id)
+            throw new Error(GUIDE_USAGE);
+        return node_id;
+    };
+    return runtime.withDocumentProjection({
+        actor_workspace_id: currentWorkspaceId(runtime),
+        operation: `guide-${action ?? 'guide'}`,
+        run: async (projection_dir) => {
+            switch (action) {
+                case 'create':
+                    return createGuide({
+                        projection_dir,
+                        journey: requiredArgument(args, '--journey'),
+                        label: requiredArgument(args, '--label'),
+                        description: argumentValue(args, '--description') ?? undefined,
+                        node_id: argumentValue(args, '--id') ?? undefined
+                    });
+                case 'export': {
+                    const file = await exportGuide({ projection_dir, node_id: requiredGuide() });
+                    const output = argumentValue(args, '--output');
+                    if (!output)
+                        return file;
+                    await writeFile(resolve(output), `${JSON.stringify(file, null, 2)}\n`);
+                    return {
+                        version: 1,
+                        status: 'written',
+                        path: resolve(output),
+                        source_hash: file.source_hash
+                    };
+                }
+                case 'update':
+                    return updateGuide({
+                        projection_dir,
+                        node_id: requiredGuide(),
+                        file: parseGuideExport(JSON.parse(await readFile(resolve(requiredArgument(args, '--file')), 'utf8')))
+                    });
+                case 'validate': {
+                    const result = await validateGuide({ projection_dir, node_id: requiredGuide() });
+                    if (!result.publishable)
+                        process.exitCode = 1;
+                    return result;
+                }
+                case 'list':
+                    return listGuides({ projection_dir });
+                default:
+                    throw new Error(GUIDE_USAGE);
+            }
+        }
+    });
+}
+/**
+ * `sdlc workspace test`: test nodes in the current workspace's projection,
+ * proposed from the spec files of the workspace's own checkout.
+ */
+async function runTestCommand(runtime, args) {
+    const [action, positional] = args;
+    return runtime.withDocumentProjection({
+        actor_workspace_id: currentWorkspaceId(runtime),
+        operation: `test-${action ?? 'test'}`,
+        run: async (projection_dir) => {
+            if (action === 'import') {
+                return importTestNodes({
+                    projection_dir,
+                    repository_root: dirname(projection_dir),
+                    parent_id: argumentValue(args, '--parent') ?? undefined,
+                    dry_run: hasFlag(args, '--dry-run')
+                });
+            }
+            if (action === 'link' &&
+                ['--verifies', '--criterion', '--journey'].filter((flag) => argumentValue(args, flag)).length > 1) {
+                throw new Error('Give one of --verifies, --criterion or --journey.');
+            }
+            if (action === 'link' &&
+                positional &&
+                !positional.startsWith('--') &&
+                argumentValue(args, '--journey')) {
+                const via = argumentValue(args, '--via');
+                return linkJourneyTest({
+                    projection_dir,
+                    node_id: positional,
+                    entry: requiredArgument(args, '--journey'),
+                    via: via
+                        ? via
+                            .split(',')
+                            .map((id) => id.trim())
+                            .filter(Boolean)
+                        : undefined
+                });
+            }
+            if (action === 'link' &&
+                positional &&
+                !positional.startsWith('--') &&
+                argumentValue(args, '--criterion')) {
+                return linkTestCriterion({
+                    projection_dir,
+                    node_id: positional,
+                    criterion: requiredArgument(args, '--criterion'),
+                    edge_id: argumentValue(args, '--id') ?? undefined
+                });
+            }
+            if (action === 'link' && positional && !positional.startsWith('--')) {
+                return linkTestNode({
+                    projection_dir,
+                    node_id: positional,
+                    target_id: requiredArgument(args, '--verifies'),
+                    edge_id: argumentValue(args, '--id') ?? undefined
+                });
+            }
+            throw new Error(TEST_USAGE);
+        }
+    });
+}
+async function runWorkspaceCommand(runtime, input) {
+    if (input.command !== 'workspace')
+        return false;
+    const subcommand = input.subcommand;
+    if (subcommand === 'init') {
+        printJson(await runtime.initializeCurrentWorkspace({
+            actor_kind: actorArgument(input.args) ?? 'human',
+            source_repository_association_id: argumentValue(input.args, '--source-association') ?? undefined,
+            source_remote_name: argumentValue(input.args, '--source-remote') ?? undefined,
+            storage_mode: storageModeArgument(input.args)
+        }));
+    }
+    else if (subcommand === 'attach' && hasFlag(input.args, '--all-members')) {
+        const given = [
+            '--source-workspace',
+            '--expected-graph-head',
+            '--source-association',
+            '--source-remote',
+            '--scope-file'
+        ].filter((flag) => argumentValue(input.args, flag) !== null);
+        if (given.length > 0) {
+            throw new Error(`attach --all-members attaches every member from this workspace's head with the entities citing it, so it takes no ${given.join(', ')}.`);
+        }
+        printJson(await runtime.attachFolderMembers({
+            actor_kind: actorArgument(input.args) ?? 'human',
+            storage_mode: storageModeArgument(input.args),
+            full_projection: hasFlag(input.args, '--full-projection')
+        }));
+    }
+    else if (subcommand === 'attach') {
+        printJson(await runtime.attachCurrentSourceWorkspace({
+            source_workspace_id: requiredArgument(input.args, '--source-workspace'),
+            expected_source_sdlc_head_commit_id: requiredArgument(input.args, '--expected-graph-head'),
+            source_repository_association_id: requiredArgument(input.args, '--source-association'),
+            source_remote_name: argumentValue(input.args, '--source-remote') ?? undefined,
+            actor_kind: actorArgument(input.args) ?? 'human',
+            storage_mode: storageModeArgument(input.args),
+            task_scope: await taskScopeArgument(input.args),
+            full_projection: hasFlag(input.args, '--full-projection')
+        }));
+    }
+    else if (subcommand === 'context') {
+        printJson(await runtime.getMultiRepositoryContext());
+    }
+    else if (subcommand === 'detach') {
+        printJson(await runtime.detachCurrentSourceWorkspace());
+    }
+    else if (subcommand === 'list') {
+        printJson({ version: 1, workspaces: runtime.listWorkspaces() });
+    }
+    else if (subcommand === 'overlap') {
+        printJson(await runtime.compareChildWorkspacePlans({
+            coordinator_workspace_id: workspaceArgument(runtime, input.args, '--coordinator')
+        }));
+    }
+    else if (subcommand === 'scope') {
+        const actor_workspace_id = currentWorkspaceId(runtime);
+        printJson(await runtime.replaceTaskScope({
+            actor_workspace_id,
+            workspace_id: argumentValue(input.args, '--workspace') ?? actor_workspace_id,
+            task_scope: await taskScopeArgument(input.args)
+        }));
+    }
+    else if (subcommand === 'export') {
+        printJson(await runtime.exportWorkspaceGraph({
+            workspace_id: workspaceArgument(runtime, input.args),
+            output_path: requiredArgument(input.args, '--output'),
+            commit_id: argumentValue(input.args, '--commit') ?? undefined,
+            view: parseClaimView(argumentValue(input.args, '--view'))
+        }));
+    }
+    else if (subcommand === 'claims') {
+        printJson(runtime.listPendingClaims({
+            workspace_id: workspaceArgument(runtime, input.args)
+        }));
+    }
+    else if (subcommand === 'claim-status') {
+        const status = argumentValue(input.args, '--status');
+        const cites_code = argumentValue(input.args, '--cites-code');
+        printJson(await runtime.workspaceClaimStatus({
+            workspace_id: workspaceArgument(runtime, input.args),
+            view: parseClaimStatusView(argumentValue(input.args, '--view')),
+            commit: argumentValue(input.args, '--commit') ?? undefined,
+            environments: argumentValues(input.args, '--environment').map(parseClaimStatusEnvironment),
+            cites_code: cites_code
+                ? cites_code
+                    .split(',')
+                    .map((type) => type.trim())
+                    .filter(Boolean)
+                : [],
+            nodes: argumentValues(input.args, '--node'),
+            status: status ? parseClaimStatus(status) : undefined,
+            stale_only: hasFlag(input.args, '--stale'),
+            behind_only: hasFlag(input.args, '--behind')
+        }));
+    }
+    else if (subcommand === 'evidence') {
+        printJson(await runEvidenceCommand(runtime, input.args));
+    }
+    else if (subcommand === 'rm') {
+        const relative_path = input.args.find((argument) => !argument.startsWith('--'));
+        if (!relative_path) {
+            throw new Error('Usage: sdlc workspace rm <entity-relative-path>');
+        }
+        printJson(await runtime.removeEntity({
+            actor_workspace_id: currentWorkspaceId(runtime),
+            relative_path
+        }));
+    }
+    else if (subcommand === 'doc') {
+        printJson(await runDocumentCommand(runtime, input.args));
+    }
+    else if (subcommand === 'test') {
+        printJson(await runTestCommand(runtime, input.args));
+    }
+    else if (subcommand === 'journey') {
+        printJson(await runJourneyCommand(runtime, input.args));
+    }
+    else if (subcommand === 'guide') {
+        printJson(await runGuideCommand(runtime, input.args));
+    }
+    else if (subcommand === 'admission') {
+        printJson(await runAdmissionCommand(runtime, input.args));
+    }
+    else if (subcommand === 'decision') {
+        printJson(await runDecisionCommand(runtime, input.args));
+    }
+    else if (subcommand === 'pick') {
+        printJson(await runPickCommand(runtime, input.args));
+    }
+    else if (subcommand === 'blast-radius') {
+        const source = requiredArgument(input.args, '--files-from');
+        const result = await runtime.workspaceBlastRadius({
+            workspace_id: workspaceArgument(runtime, input.args),
+            files: parseFileList(source === '-'
+                ? await readStream(process.stdin)
+                : await readFile(resolve(source), 'utf8')),
+            view: parseClaimView(argumentValue(input.args, '--view'))
+        });
+        for (const warning of result.warnings ?? []) {
+            process.stderr.write(`warning: ${warning}\n`);
+        }
+        printJson(result);
+    }
+    else if (subcommand === 'find') {
+        const options = optionArguments(input.args);
+        const terms = readArguments(input.args, [], FIND_USAGE);
+        if (terms.length === 0)
+            throw new Error(FIND_USAGE);
+        const types = argumentValue(options, '--type');
+        if (types !== null && !types.split(',').some((type) => type.trim())) {
+            throw new Error(`--type needs a value. ${FIND_USAGE}`);
+        }
+        const origin = argumentValue(options, '--origin');
+        if (origin !== null && origin !== 'built' && origin !== 'shelf') {
+            throw new Error(`--origin takes built or shelf. ${FIND_USAGE}`);
+        }
+        const limit = argumentValue(options, '--limit');
+        const result = await runtime.workspaceFind({
+            workspace_id: workspaceArgument(runtime, options),
+            terms,
+            types: types
+                ? types
+                    .split(',')
+                    .map((type) => type.trim())
+                    .filter(Boolean)
+                : undefined,
+            origin: origin ?? undefined,
+            limit: limit === null ? undefined : positiveInteger(limit, '--limit'),
+            view: parseClaimView(argumentValue(options, '--view'))
+        });
+        for (const warning of result.warnings ?? []) {
+            process.stderr.write(`warning: ${warning}\n`);
+        }
+        printJson(result);
+    }
+    else if (subcommand === 'show') {
+        const options = optionArguments(input.args);
+        const ids = readArguments(input.args, ['--full'], SHOW_USAGE);
+        if (ids.length === 0)
+            throw new Error(SHOW_USAGE);
+        const budget = argumentValue(options, '--budget');
+        if (budget !== null && hasFlag(options, '--full')) {
+            throw new Error(`--full shows each entity whole; leave out --budget. ${SHOW_USAGE}`);
+        }
+        const result = await runtime.workspaceShow({
+            workspace_id: workspaceArgument(runtime, options),
+            ids,
+            budget: hasFlag(options, '--full')
+                ? null
+                : budget === null
+                    ? undefined
+                    : positiveInteger(budget, '--budget'),
+            view: parseClaimView(argumentValue(options, '--view'))
+        });
+        for (const warning of result.warnings ?? []) {
+            process.stderr.write(`warning: ${warning}\n`);
+        }
+        printJson(result);
+    }
+    else if (subcommand === 'status') {
+        printJson(await runtime.getWorkspaceStatus(workspaceArgument(runtime, input.args)));
+    }
+    else if (subcommand === 'authority') {
+        printJson(runtime.inspectAuthority());
+    }
+    else if (subcommand === 'create') {
+        printJson(await runtime.createChildWorkspace({
+            actor_workspace_id: workspaceArgument(runtime, input.args, '--from'),
+            target_path: resolve(requiredArgument(input.args, '--path')),
+            actor_kind: actorArgument(input.args) ?? 'ai',
+            task_scope: await taskScopeArgument(input.args)
+        }));
+    }
+    else if (subcommand === 'commit') {
+        printJson(await runtime.commitCurrentProjection({
+            actor_workspace_id: workspaceArgument(runtime, input.args),
+            message: requiredArgument(input.args, '--message')
+        }));
+    }
+    else if (subcommand === 'recover') {
+        printJson(await runtime.recoverCurrentProjection({
+            actor_workspace_id: workspaceArgument(runtime, input.args),
+            expected_head_commit_id: requiredArgument(input.args, '--expected-head'),
+            expected_projection_root_hash: argumentValue(input.args, '--expected-projection-root') ?? undefined,
+            discard_unreadable_projection: hasFlag(input.args, '--discard-unreadable')
+        }));
+    }
+    else if (subcommand === 'close') {
+        const actor_workspace_id = currentWorkspaceId(runtime);
+        printJson({
+            version: 1,
+            workspace: await runtime.closeWorkspace({
+                actor_workspace_id,
+                workspace_id: argumentValue(input.args, '--workspace') ?? actor_workspace_id
+            })
+        });
+    }
+    else if (subcommand === 'prune') {
+        const min_age_value = argumentValue(input.args, '--min-age-hours');
+        const min_age_hours = min_age_value === null ? undefined : Number(min_age_value);
+        printJson(hasFlag(input.args, '--apply')
+            ? await runtime.applyPrune({
+                expected_plan_hash: requiredArgument(input.args, '--expected-plan-hash'),
+                min_age_hours
+            })
+            : await runtime.planPrune({ min_age_hours }));
+    }
+    else {
+        return false;
+    }
+    return true;
+}
+async function runCoordinationCommand(runtime, input) {
+    const key = `${input.command}:${input.subcommand ?? ''}`;
+    if (key === 'integrate:enqueue') {
+        printJson({
+            version: 1,
+            queue_entry: await runtime.enqueueChildCommit({
+                actor_workspace_id: workspaceArgument(runtime, input.args, '--coordinator'),
+                child_workspace_id: requiredArgument(input.args, '--workspace'),
+                child_commit_id: argumentValue(input.args, '--commit') ?? undefined,
+                gate: gateArgument(input.args)
+            })
+        });
+    }
+    else if (key === 'integrate:run' || key === 'integrate:reconcile') {
+        const retry_value = argumentValue(input.args, '--max-retries');
+        const common = {
+            actor_workspace_id: workspaceArgument(runtime, input.args, '--coordinator'),
+            max_retries: retry_value === null ? undefined : Number(retry_value),
+            ...(await resolverArguments(runtime, input.args))
+        };
+        const result = key === 'integrate:run'
+            ? await runtime.integrateNext(common)
+            : await runtime.reconcileSource({
+                ...common,
+                source_workspace_id: requiredArgument(input.args, '--source')
+            });
+        printJson(result);
+        if (result.status === 'blocked_conflict' ||
+            result.status === 'blocked_validation') {
+            process.exitCode = 2;
+        }
+    }
+    else if (key === 'handoff:prepare') {
+        const retry_value = argumentValue(input.args, '--max-retries');
+        const result = await runtime.prepareHandoff({
+            actor_workspace_id: workspaceArgument(runtime, input.args),
+            source_workspace_id: requiredArgument(input.args, '--source'),
+            max_retries: retry_value === null ? undefined : Number(retry_value),
+            ...(await resolverArguments(runtime, input.args))
+        });
+        printJson(result);
+        if (result.status !== 'ready')
+            process.exitCode = 2;
+    }
+    else if (key === 'handoff:list') {
+        printJson({
+            version: 1,
+            handoffs: await runtime.listHandoffs(workspaceArgument(runtime, input.args))
+        });
+    }
+    else if (key === 'handoff:inspect' || key === 'handoff:apply') {
+        const common = {
+            actor_workspace_id: workspaceArgument(runtime, input.args),
+            handoff_id: requiredArgument(input.args, '--handoff')
+        };
+        const result = key === 'handoff:inspect'
+            ? await runtime.inspectHandoff(common)
+            : await runtime.applyHandoff(common);
+        printJson(result);
+        if (key === 'handoff:apply' && result.status !== 'applied')
+            process.exitCode = 2;
+    }
+    else {
+        return false;
+    }
+    return true;
+}
+export async function runLocalWorkspaceCommand(input) {
+    if (input.command === 'topology') {
+        if (input.subcommand === 'inspect') {
+            printJson(await inspectWorkspaceTopology());
+        }
+        else if (input.subcommand === 'relocate') {
+            const relocation = {
+                target_state_dir: resolve(requiredArgument(input.args, '--state-dir')),
+                target_storage_mode: storageModeArgument(input.args, true)
+            };
+            printJson(hasFlag(input.args, '--apply')
+                ? await applyWorkspaceStorageRelocation({
+                    ...relocation,
+                    expected_plan_hash: requiredArgument(input.args, '--expected-plan-hash')
+                })
+                : await planWorkspaceStorageRelocation(relocation));
+        }
+        else if (input.subcommand === 'export') {
+            printJson(await exportWorkspaceStorage({
+                bundle_dir: resolve(requiredArgument(input.args, '--path'))
+            }));
+        }
+        else if (input.subcommand === 'recover') {
+            printJson(await recoverWorkspaceStorageRelocation());
+        }
+        else if (input.subcommand === 'clone') {
+            printJson(await cloneWorkspaceStorage({
+                bundle_dir: resolve(requiredArgument(input.args, '--from')),
+                target_state_dir: resolve(requiredArgument(input.args, '--state-dir')),
+                expected_graph_repository_id: requiredArgument(input.args, '--graph-repository-id')
+            }));
+        }
+        else {
+            throw new Error('Usage: sdlc topology inspect | relocate --state-dir <path> --storage-mode <machine_shared|self_contained> [--apply --expected-plan-hash <sha256>] | export --path <directory> | recover | clone --from <directory> --state-dir <path> --graph-repository-id <uuid>');
+        }
+        return;
+    }
+    if (input.command === 'workspace' &&
+        input.subcommand === 'evidence' &&
+        input.args[0] === 'verify') {
+        await runEvidenceVerify(input.args);
+        return;
+    }
+    // `sdlc variants` takes no subcommand, so its first flag arrives as one.
+    const open_args = input.command === 'variants'
+        ? [input.subcommand, ...input.args].filter((value) => typeof value === 'string')
+        : input.command === 'workspace' &&
+            (input.subcommand === 'find' || input.subcommand === 'show')
+            ? optionArguments(input.args)
+            : input.args;
+    // The evidence writer and readers name the workspace by its worktree (--graph).
+    const graph_worktree = input.command === 'workspace' && input.subcommand === 'evidence'
+        ? argumentValue(open_args, '--graph')
+        : null;
+    const runtime = await LocalWorkspaceRuntime.open({
+        ...(graph_worktree ? { cwd: resolve(graph_worktree) } : {}),
+        state_dir: argumentValue(open_args, '--repository-state-dir') ?? undefined,
+        graph_repository_id: argumentValue(open_args, '--graph-repository-id') ?? undefined
+    });
+    try {
+        if (input.command === 'variants') {
+            // sdlc variants [--workspace <id>] [--commit <ref>] [--environment <key>=<ref>]... [--json]
+            const args = open_args;
+            const report = await runtime.workspaceVariants({
+                workspace_id: workspaceArgument(runtime, args),
+                commit: argumentValue(args, '--commit') ?? undefined,
+                environments: argumentValues(args, '--environment').map(parseClaimStatusEnvironment)
+            });
+            if (hasFlag(args, '--json'))
+                printJson(report);
+            else
+                console.log(formatVariantsReport(report));
+            return;
+        }
+        if (input.command === 'viewer') {
+            const port_value = argumentValue(input.args, '--port');
+            // The engine panels come from sdlc view's code, which the public CLI ships without
+            // (view-seam.ts): without it they are absent and the domain pages answer engine_missing.
+            // Pins are view state and Done a coordination record (status user-done), both beside the
+            // Threads panel; the Releases (rl-ui-viewer) and Work queues (qv-viewer) panels read on their own.
+            const { threads, pin, taskDone, releaseLinks, queues, domains } = viewerProviders(await loadViewModule(), process.cwd());
+            // The shared pages' contract reads (api/app/…): the shell's own in any Git repository
+            // (la-shell), and the domain reads through the engine's readers where it resolves (la-contracts).
+            // The Worktrees page reads and writes through the main checkout's engine (la-worktrees).
+            const worktrees = worktreesProvider(process.cwd()) ?? undefined;
+            const app = appShellReader({ cwd: process.cwd(), domains, worktrees });
+            const viewer = await startLocalWorkspaceViewer({
+                runtime,
+                port: port_value === null ? undefined : Number(port_value),
+                threads,
+                pin,
+                taskDone,
+                releaseLinks,
+                queues,
+                app,
+                worktrees: worktrees?.current ? worktrees : undefined
+            });
+            printJson(viewerStartLine(viewer.url, Boolean(pin), viewer.page, Boolean(taskDone), Boolean(worktrees?.current)));
+            const stop = () => void viewer.close();
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+            try {
+                await viewer.closed;
+            }
+            finally {
+                process.off('SIGINT', stop);
+                process.off('SIGTERM', stop);
+            }
+            return;
+        }
+        if (['remote', 'portable', 'branch', 'merge', 'resolver'].includes(input.command) &&
+            (await runEnvironmentCommand(runtime, input))) {
+            return;
+        }
+        if ((await runWorkspaceCommand(runtime, input)) ||
+            (await runCoordinationCommand(runtime, input))) {
+            return;
+        }
+        throw new Error('Usage: sdlc viewer [--port <0..65535>] | sdlc topology inspect|relocate|export|recover|clone | sdlc remote set|list|inspect|remove|discover|refs|fetch|push|push-journals|topic|topic-journals|pr|pr-journals | sdlc branch create|list|select | sdlc merge upstream|status|revert|attempts|resolution-attempts|reverts | sdlc portable plan|convert | sdlc workspace init|attach|context|list|overlap|scope|export|claims|claim-status|find|show|evidence|rm|doc|decision|pick|status|authority|create|commit|recover|close|detach|prune | sdlc resolver configure|status|clear | sdlc integrate enqueue|run|reconcile | sdlc handoff prepare|list|inspect|apply');
+    }
+    finally {
+        runtime.close();
+    }
+}
+//# sourceMappingURL=workspace-cli.js.map