@empire-builder-kit/nx 1.0.0-rc.38 → 1.0.0-rc.39

package/src/cli/main.js

@@ -34,7 +34,10 @@ const secret_slice_claim_js_1 = require("../local-dev/secret-slice-claim.js");
 const tls_js_1 = require("../local-dev/tls.js");
 const personal_command_js_1 = require("../secrets/personal-command.js");
 const index_js_1 = require("../workspace-deployment/index.js");
+const task_attachment_js_1 = require("../local-dev/task-attachment.js");
+const task_identity_js_1 = require("../local-dev/task-identity.js");
 const dev_command_js_1 = require("./dev-command.js");
+const deploy_runtime_js_1 = require("./deploy-runtime.js");
 const agent_runtime_js_1 = require("./agent-runtime.js");
 const output_js_1 = require("./output.js");
 const personal_secret_runtime_js_1 = require("./personal-secret-runtime.js");
@@ -44,11 +47,32 @@ const ROOT_HELP = `Empire Builder Kit
 Usage:
   ebk agent <command> [options]
   ebk blueprint verification-review
+  ebk deploy [stage] [slice...] [options]
   ebk dev <command> [options]
   ebk secret <command> <slice> <logical-name>
 
-Run "ebk agent --help", "ebk blueprint --help", "ebk dev --help", or
+Run "ebk agent --help", "ebk blueprint --help", "ebk deploy --help", "ebk dev --help", or
 "ebk secret --help" for namespace help.`;
+const DEPLOY_HELP = `Empire Builder Kit local deployment
+
+Usage:
+  ebk deploy [development|staging|production] [slice...] --expectedRoleArn=<role-arn> [--profile=<aws-profile>]
+
+The stage defaults to development; --stage=<stage> is also supported instead
+of a positional stage. Account and Region come from committed repository policy.
+Uses the workspace-pinned Nx deploy-local target: Foundation, then eligible
+Slices, declared migrations and deployed smoke. Supply billing to deploy only
+that Slice after Foundation; omit Slice names for the complete stage. Other
+Slices are not redeployed and must already exist if the feature needs them.
+Native output and terminal
+interaction are inherited; --json and arbitrary Nx/SST options are not accepted.
+The existing deployment receipt is the structured result, not a CLI success seal.
+
+Development allows dirty source without a prompt. Local staging requires a
+clean commit and its TTY acknowledgement. Starter production requires a clean
+commit and the exact deploy:production:<account>:<region>:<source-commit> TTY
+confirmation. Isolated protected stages remain GitHub-only. No authority or
+confirmation is inferred from a hot task; ebk dev up remains the hot edit loop.`;
 const AGENT_HELP = `Empire Builder Kit Developer-Agent contract
 
 Usage:
@@ -76,6 +100,7 @@ Usage:
   ebk dev configure [<context options>] [--clear-development-router-url] [--json]
   ebk dev setup [--trust] [--portless] [--upgrade] [--remove] [--json]
   ebk dev up <slice...>|--all [--foreground] [--sst-mode=mono|multiplexer]
+  ebk dev attach <task-id> [--json]
              [--no-wait] [--timeout=<duration>] [<context options>] [--json]
   ebk dev status [--json]
   ebk dev restart <slice...>|--all [--no-wait] [--timeout=<duration>] [--json]
@@ -99,7 +124,8 @@ Configure mutation requires at least one context option or
 non-router context changes.
 
 Use "ebk dev <command> --help" to return this bounded command reference.
-Fleet stage is always derived from the current operating-system account.`;
+Fleet stage uses a persisted random task ID per worktree. Use attach explicitly
+to resume a verified inactive task; --stage overrides are not supported.`;
 const SECRET_HELP = `Empire Builder Kit personal secrets
 
 Usage:
@@ -143,13 +169,12 @@ function packageVersion() {
 }
 function workspaceRoot(cwd) {
     try {
-        const root = (0, node_child_process_1.execFileSync)('git', [
+        const git = (args) => (0, node_child_process_1.execFileSync)('git', [
             '--no-optional-locks',
             '-c',
             'core.fsmonitor=false',
             'rev-parse',
-            '--path-format=absolute',
-            '--show-toplevel',
+            ...args,
         ], {
             cwd,
             encoding: 'utf8',
@@ -158,9 +183,22 @@ function workspaceRoot(cwd) {
             timeout: 5_000,
             windowsHide: true,
         }).trim();
-        if (!(0, node_path_1.isAbsolute)(root))
+        const toplevel = git(['--path-format=absolute', '--show-toplevel']);
+        if (!(0, node_path_1.isAbsolute)(toplevel))
             throw new Error('Git returned a relative path.');
-        return (0, node_fs_1.realpathSync)(root);
+        // Spell the root the way this process's working directory spells it. Git
+        // canonicalizes Windows 8.3 aliases to long names while every in-process
+        // resolver, the fleet runtime and the retained task pointer use realpathSync,
+        // so a checkout under an aliased directory (a hosted runner's TEMP) would
+        // otherwise be seen under two spellings and refused as another checkout.
+        let root = (0, node_fs_1.realpathSync)(cwd);
+        for (const segment of git(['--show-prefix']).split('/')) {
+            if (segment)
+                root = (0, node_path_1.dirname)(root);
+        }
+        if (node_fs_1.realpathSync.native(root) !== node_fs_1.realpathSync.native(toplevel))
+            throw new Error('Git toplevel does not match the working directory.');
+        return root;
     }
     catch {
         throw new errors_js_1.LocalDevContractError('prerequisite-unavailable', 'Run ebk from a Git workspace with a readable repository root.');
@@ -168,6 +206,8 @@ function workspaceRoot(cwd) {
 }
 function defaultDependencies(overrides) {
     return {
+        attachTask: task_attachment_js_1.attachStoppedTask,
+        bindTask: task_identity_js_1.bindTaskEnvironment,
         acquireSecretLedgerLock: personal_secret_ledger_js_1.acquirePersonalSecretLedgerLock,
         appData: tls_js_1.defaultLocalDevAppData,
         assertSecretSliceClaim: secret_slice_claim_js_1.assertSecretSliceClaimAuthority,
@@ -176,6 +216,7 @@ function defaultDependencies(overrides) {
         client: (paths) => new fleet_client_js_1.FleetClient(paths),
         discoverContext: context_discovery_js_1.discoverLocalDevContext,
         executeAgent: agent_runtime_js_1.executeDeveloperAgentCommand,
+        executeDeploy: deploy_runtime_js_1.executeDeployCommand,
         followLogs: fleet_logs_js_1.followFleetLogs,
         frameworkVersion: packageVersion,
         gitCommonDirectory: fleet_launcher_js_1.resolveGitCommonDirectory,
@@ -226,7 +267,7 @@ function planWorkspaceName(plan) {
 }
 async function resolveCurrentFleetCoordinates(workspaceRoot, appData, dependencies) {
     const plan = await dependencies.loadPlan();
-    const identity = dependencies.personalStageResolver.resolve();
+    const identity = dependencies.personalStageResolver.resolve(workspaceRoot);
     const workspaceName = planWorkspaceName(plan);
     const fleetId = (0, identity_js_1.createFleetId)({
         checkoutPath: workspaceRoot,
@@ -242,7 +283,7 @@ async function resolveCurrentFleetCoordinates(workspaceRoot, appData, dependenci
     };
 }
 async function resolveRecoveryFleetCoordinates(workspaceRoot, appData, dependencies, currentPlatform = process.platform) {
-    const identity = dependencies.personalStageResolver.resolve();
+    const identity = dependencies.personalStageResolver.resolve(workspaceRoot);
     const inventory = await dependencies.inventory({ appData });
     const matches = inventory.filter(({ checkout, stage }) => checkout !== undefined &&
         sameWorkspaceRealpath(checkout, workspaceRoot, currentPlatform) &&
@@ -420,7 +461,7 @@ async function executeSecretCommand(command, dispatch) {
                 : 'Personal secret commands require saved local-development profile and Region context. Run ebk dev configure first.');
         }
         const context = saved.resolution.context;
-        const identity = dispatch.dependencies.personalStageResolver.resolve();
+        const identity = dispatch.dependencies.personalStageResolver.resolve(dispatch.workspaceRoot);
         const environmentAssessment = await dispatch.dependencies.inspectEnvironment({
             appData: dispatch.appData,
             command: 'secret',
@@ -466,6 +507,11 @@ async function executeSecretCommand(command, dispatch) {
             if (ownership.region !== context.region) {
                 throw new Error('Personal secret Region differs from workspace owner.');
             }
+            dispatch.dependencies.bindTask(dispatch.workspaceRoot, {
+                accountId,
+                region: ownership.region,
+                workspaceDeploymentId: ownership.expectedOwner.workspaceDeploymentId,
+            });
         }
         catch {
             throw new errors_js_1.LocalDevContractError('prerequisite-unavailable', 'The development AWS tuple is not owned by this workspace. Run the generated workspace ownership doctor before personal secret mutation.');
@@ -574,7 +620,7 @@ async function recordDiagnosticAssessment(command, dispatch) {
         command,
         context,
         frameworkVersion: dispatch.dependencies.frameworkVersion(),
-        identity: dispatch.dependencies.personalStageResolver.resolve(),
+        identity: dispatch.dependencies.personalStageResolver.resolve(dispatch.workspaceRoot),
         workspaceRoot: dispatch.workspaceRoot,
     });
 }
@@ -760,7 +806,26 @@ async function executeDown(command, coordinates, dispatch) {
             throw new errors_js_1.LocalDevContractError('unknown-slice', `Product Slice ${unknown} is absent from the live Fleet state.`);
         }
     }
-    const submission = await client.submit('down', command.selector, dispatch.dependencies.idempotencyKey());
+    let submission;
+    try {
+        submission = await client.submit('down', command.selector, dispatch.dependencies.idempotencyKey());
+    }
+    catch (error) {
+        if (!command.selector.all ||
+            !(error instanceof errors_js_1.LocalDevContractError) ||
+            error.classification !== 'not-running')
+            throw error;
+        // This remains an authenticated shutdown request. The supervisor checks
+        // in-flight work, active selections, and owned cleanup independently.
+        await client.shutdown(dispatch.dependencies.idempotencyKey());
+        return {
+            result: success(command.command, {
+                fleetId: coordinates.fleetId,
+                alreadyEmpty: true,
+                shutdown: 'accepted',
+            }),
+        };
+    }
     if (command.noWait) {
         return {
             result: success(command.command, { fleetId: coordinates.fleetId, operation: submission }, submission.operationId),
@@ -885,12 +950,27 @@ async function executeDoctor(command, identity, dispatch) {
         dispatch.dependencies.inventoryClaims({ appData: dispatch.appData }),
     ]);
     const outcome = doctorOutcome(environment, local);
+    const diagnostics = [
+        ...environment.checks
+            .filter(({ status }) => !['ready', 'unverified', 'not-required'].includes(status))
+            .map(({ id, status, remediation }) => `${id}=${status}${remediation ? `: ${remediation}` : ''}`),
+        ...(local?.issues ?? []),
+    ]
+        .slice(0, 8)
+        .map((message) => message.slice(0, 512));
     const payload = {
         context: contextPayload(saved),
         environmentAssessment: environment,
         fleetInventory,
         ...(local ? { localDevelopment: local } : {}),
         sliceClaims,
+        ...(outcome.outcome === 'failed'
+            ? {
+                message: diagnostics.length > 0
+                    ? diagnostics.join(' ')
+                    : 'Development readiness is incomplete. Run ebk dev doctor --refresh --json to inspect the exact prerequisite.',
+            }
+            : {}),
     };
     return {
         result: outcome.outcome === 'succeeded'
@@ -996,6 +1076,26 @@ async function executeSetup(command, identity, dispatch) {
     };
 }
 async function dispatchDevCommand(command, dispatch) {
+    if (command.command === 'attach') {
+        const saved = dispatch.dependencies.readContext(dispatch.dependencies.gitCommonDirectory(dispatch.workspaceRoot));
+        if (saved.kind !== 'ready')
+            throw new errors_js_1.LocalDevContractError('local-context-missing', 'Task attachment requires saved AWS context. Run ebk dev configure first.');
+        const plan = await dispatch.dependencies.loadPlan();
+        const task = await dispatch.dependencies.attachTask({
+            appData: dispatch.appData,
+            context: saved.resolution.context,
+            taskId: command.taskId,
+            workspaceName: planWorkspaceName(plan),
+            workspaceRoot: dispatch.workspaceRoot,
+        });
+        return {
+            result: success('attach', {
+                taskId: task.taskId,
+                stage: `personal-${task.taskId}`,
+                nextAction: 'ebk dev up <slice...>',
+            }),
+        };
+    }
     if (command.command === 'ps') {
         await recordDiagnosticAssessment('ps', dispatch);
         const [fleets, sliceClaims] = await Promise.all([
@@ -1019,13 +1119,13 @@ async function dispatchDevCommand(command, dispatch) {
         await recordDiagnosticAssessment(command.command, dispatch);
     }
     if (command.command === 'configure') {
-        return executeConfigure(command, dispatch.dependencies.personalStageResolver.resolve(), dispatch);
+        return executeConfigure(command, dispatch.dependencies.personalStageResolver.resolve(dispatch.workspaceRoot), dispatch);
     }
     if (command.command === 'setup') {
-        return executeSetup(command, dispatch.dependencies.personalStageResolver.resolve(), dispatch);
+        return executeSetup(command, dispatch.dependencies.personalStageResolver.resolve(dispatch.workspaceRoot), dispatch);
     }
     if (command.command === 'doctor') {
-        return executeDoctor(command, dispatch.dependencies.personalStageResolver.resolve(), dispatch);
+        return executeDoctor(command, dispatch.dependencies.personalStageResolver.resolve(dispatch.workspaceRoot), dispatch);
     }
     if (command.command === 'up' || command.command === 'restart') {
         const coordinates = await resolveCurrentFleetCoordinates(dispatch.workspaceRoot, dispatch.appData, dispatch.dependencies);
@@ -1063,12 +1163,15 @@ function commandJson(command) {
 }
 function commandName(command) {
     return command?.kind === 'agent' ||
+        command?.kind === 'deploy' ||
         command?.kind === 'dev' ||
         command?.kind === 'secret'
         ? command.command
         : 'parse';
 }
 function commandNamespace(command, arguments_) {
+    if (command?.kind === 'deploy' || arguments_[0] === 'deploy')
+        return 'deploy';
     if (command?.kind === 'agent' || arguments_[0] === 'agent')
         return 'agent';
     return command?.kind === 'secret' || arguments_[0] === 'secret'
@@ -1155,11 +1258,13 @@ async function runEbkCli(arguments_, io = {}, overrides = {}) {
         if (parsed.kind === 'help') {
             output.stdout(`${parsed.namespace === 'agent'
                 ? AGENT_HELP
-                : parsed.namespace === 'dev'
-                    ? DEV_HELP
-                    : parsed.namespace === 'secret'
-                        ? SECRET_HELP
-                        : ROOT_HELP}\n`);
+                : parsed.namespace === 'deploy'
+                    ? DEPLOY_HELP
+                    : parsed.namespace === 'dev'
+                        ? DEV_HELP
+                        : parsed.namespace === 'secret'
+                            ? SECRET_HELP
+                            : ROOT_HELP}\n`);
             return 0;
         }
         if (parsed.kind === 'version') {
@@ -1174,6 +1279,9 @@ async function runEbkCli(arguments_, io = {}, overrides = {}) {
         }
         const dependencies = defaultDependencies(overrides);
         const root = dependencies.resolveWorkspaceRoot(io.cwd ?? process.cwd());
+        if (parsed.kind === 'deploy') {
+            return await dependencies.executeDeploy(parsed, root, io.environment ?? process.env);
+        }
         dependencies.changeDirectory(root);
         if (!io.abortSignal)
             ownedSignal = processAbortSignal();

package/src/cli/output.d.ts

@@ -9,7 +9,7 @@ export type CliFailureClassification = DeveloperAgentFailureClassification | Loc
 export interface CliResultEnvelope<TPayload = unknown> {
     command: string;
     failureClassification?: CliFailureClassification;
-    namespace: 'agent' | 'dev' | 'secret';
+    namespace: 'agent' | 'deploy' | 'dev' | 'secret';
     operationId?: string;
     outcome: CliResultOutcome;
     payload?: TPayload;

package/src/developer-agent/context.js

@@ -213,6 +213,13 @@ function gitContext(inspection) {
 }
 function gitWarnings(inspection) {
     const warnings = [];
+    if (inspection.worktree.commit === null ||
+        inspection.defaultBase?.commit === null) {
+        warnings.push({
+            classification: 'stale-base',
+            sanitizedSummary: 'Local source is available, but commit-bound planning, handoff, and protected authority require real Git commits and protected refs. No commit or remote ref was created by orientation.',
+        });
+    }
     if (inspection.worktree.dirtyPaths.length > 0) {
         warnings.push({
             classification: 'dirty-worktree',
@@ -335,6 +342,8 @@ async function inspectDeveloperAgentContext(cwd, query = {}, dependencyOverrides
     const workspaceRoot = (0, node_fs_1.realpathSync)(cwd);
     const nxConfiguration = workspaceNxExecutionConfiguration(workspaceRoot);
     const gitOptions = {
+        allowMissingDefaultBase: true,
+        allowUnborn: true,
         ...(query.base ? { base: query.base } : {}),
         cwd: workspaceRoot,
         defaultBase: nxConfiguration.defaultBaseRef,
@@ -355,11 +364,21 @@ async function inspectDeveloperAgentContext(cwd, query = {}, dependencyOverrides
     try {
         const currentExternalRoots = (0, blueprint_verification_authority_js_1.externalBlueprintOwnershipRoots)(workspaceRoot);
         (0, blueprint_verification_authority_js_1.assertDeveloperAgentNxProjectConfinement)(workspaceRoot);
+        // Orientation can describe an unborn worktree, but it cannot establish
+        // protected history. Keep package target authority strict; this is not an
+        // alternate path to a protected review or execution receipt.
         externalOwnershipHistory =
-            (0, blueprint_trust_git_js_1.inspectProtectedWorkspaceExternalBlueprintHistory)({
-                builtInName: resolver_js_1.BUILTIN_BLUEPRINT_NAME,
-                workspaceRoot,
-            });
+            gitInspection.worktree.commit === null
+                ? {
+                    complete: false,
+                    externalProjectNames: [],
+                    externalSliceRoots: [],
+                    requiresStrictNxAuthority: true,
+                }
+                : (0, blueprint_trust_git_js_1.inspectProtectedWorkspaceExternalBlueprintHistory)({
+                    builtInName: resolver_js_1.BUILTIN_BLUEPRINT_NAME,
+                    workspaceRoot,
+                });
         if (currentExternalRoots.length > 0 ||
             externalOwnershipHistory.requiresStrictNxAuthority) {
             (0, blueprint_verification_authority_js_1.assertNoMutableBlueprintVerificationConfiguration)(workspaceRoot);
@@ -443,7 +462,7 @@ function formatDeveloperAgentContext(context) {
     ].sort(ordering_js_1.compareDeveloperAgentStrings);
     const lines = [
         `Workspace: ${context.workspace.identity} (${context.workspace.frameworkVersion})`,
-        `Git: ${branch} @ ${context.git.commit.slice(0, 12)}${context.git.dirty ? ' (dirty)' : ''}`,
+        `Git: ${branch} @ ${context.git.commit?.slice(0, 12) ?? '(uncommitted)'}${context.git.dirty ? ' (dirty)' : ''}`,
         `Selection: ${selection}`,
         `Nx graph projects: ${context.projectNames.length}`,
         `Policy stage: ${context.policy.canonicalStage}`,
@@ -458,6 +477,15 @@ function formatDeveloperAgentContext(context) {
             : ''}`,
     ];
     const details = [
+        ...context.supportedOperations
+            .filter((operation) => operation.command &&
+            (operation.id.startsWith('ebk-dev:') ||
+                operation.id.endsWith(':verify-local-browser') ||
+                operation.id.endsWith(':dev')))
+            .map((operation) => ({
+            kind: 'operation',
+            line: `- [operation] ${operation.id}: ${operation.command.executable} ${operation.command.args.map((argument) => (/^[A-Za-z0-9_./:@=-]+$/.test(argument) ? argument : JSON.stringify(argument))).join(' ')}`,
+        })),
         ...context.warnings.map((finding) => ({
             kind: 'warning',
             line: `- [${finding.classification}] ${finding.sanitizedSummary}`,
@@ -469,8 +497,9 @@ function formatDeveloperAgentContext(context) {
     ];
     let omittedWarnings = 0;
     let omittedNonPlannable = 0;
+    let omittedOperations = 0;
     const route = 'Full structured context: ebk agent context --json';
-    const maximumOmission = `Omitted detail: ${context.warnings.length} warning(s), ${context.nonPlannableTargets.length} non-plannable target(s).`;
+    const maximumOmission = `Omitted detail: ${context.warnings.length} warning(s), ${context.nonPlannableTargets.length} non-plannable target(s), ${context.supportedOperations.length} operation(s).`;
     for (const detail of details) {
         const candidate = [...lines, detail.line, maximumOmission, route].join('\n');
         if (Buffer.byteLength(candidate, 'utf8') <=
@@ -480,12 +509,15 @@ function formatDeveloperAgentContext(context) {
         else if (detail.kind === 'warning') {
             omittedWarnings += 1;
         }
-        else {
+        else if (detail.kind === 'non-plannable') {
             omittedNonPlannable += 1;
         }
+        else {
+            omittedOperations += 1;
+        }
     }
-    if (omittedWarnings > 0 || omittedNonPlannable > 0) {
-        lines.push(`Omitted detail: ${omittedWarnings} warning(s), ${omittedNonPlannable} non-plannable target(s).`);
+    if (omittedWarnings > 0 || omittedNonPlannable > 0 || omittedOperations > 0) {
+        lines.push(`Omitted detail: ${omittedWarnings} warning(s), ${omittedNonPlannable} non-plannable target(s), ${omittedOperations} operation(s).`);
     }
     lines.push(route);
     const output = lines.join('\n');

package/src/developer-agent/generator-planning.js

@@ -185,7 +185,9 @@ function generatorContextSelection(input) {
         input.generator === 'job') {
         return {
             selectedFeature: input.feature,
-            selectedProjects: [input.slice],
+            selectedProjects: input.generator === 'function'
+                ? [input.slice]
+                : [input.slice, 'foundation'].sort(),
             selectedSlice: input.slice,
         };
     }
@@ -425,6 +427,7 @@ function workloadPlan(context, input, mode, rebindCompleted = false) {
     const generatedSurfaces = sortedSurfaces([
         ...prefixedSurfaces(input.slice, plan.paths),
         ...prefixedSurfaces(input.slice, [
+            { path: 'infra/foundation.ts' },
             { path: 'infra/product.ts' },
             { path: 'infra/native-runtime-authority/effective-intent.ts' },
             { path: 'infra/native-runtime-authority/topology.ts' },
@@ -447,6 +450,16 @@ function workloadPlan(context, input, mode, rebindCompleted = false) {
             { mode: 'seeded', path: RELEASE_REGISTRY_PATH },
             { path: PRODUCT_OWNERSHIP_PATH },
         ]),
+        // The workload generator grows network/container-compute capabilities in
+        // the same source operation. These are its paired Foundation surfaces,
+        // even when an existing container makes the capability update a no-op.
+        ...prefixedSurfaces('foundation', [
+            { path: PRODUCT_OWNERSHIP_PATH },
+            { path: 'contracts/costs.json' },
+            { path: 'contracts/foundation.json' },
+            { path: 'infra/foundation.ts' },
+            { path: 'scripts/verify-foundation.mjs' },
+        ]),
         surface('pnpm-lock.yaml', 'adopter-owned'),
     ]);
     const prospectiveVerification = mode === 'apply' ? [`${plan.project}:verify`] : [];
@@ -469,11 +482,12 @@ function workloadPlan(context, input, mode, rebindCompleted = false) {
             'supply-chain',
         ], context.selection.contracts),
         generatedSurfaces,
-        projects: [input.slice, plan.project].sort(),
+        projects: [input.slice, plan.project, 'foundation'].sort(),
         prospectiveVerification,
         verification: [
             ...new Set([
                 `${input.slice}:verify`,
+                'foundation:verify',
                 ...prospectiveVerification,
                 developerAgentWorkspaceVerificationTarget(context),
             ]),

package/src/developer-agent/git-inspection.d.ts

@@ -26,6 +26,10 @@ export interface GitInspectionCommandResult {
 }
 export type GitInspectionExecFile = (executable: string, args: readonly string[], options: GitInspectionExecFileOptions) => GitInspectionCommandResult | Promise<GitInspectionCommandResult>;
 export interface InspectDeveloperAgentGitOptions {
+    /** Orientation only; strict commit-bound callers leave this disabled. */
+    allowUnborn?: boolean;
+    /** Only an absent fully qualified implicit ref may have a null binding. */
+    allowMissingDefaultBase?: boolean;
     /**
      * Base and head are accepted only as a pair. They must be literal safe refs
      * or full object IDs, never arbitrary revision expressions.
@@ -44,7 +48,7 @@ export interface DeveloperAgentGitUpstream {
 }
 export interface DeveloperAgentLinkedWorktree {
     branch: string | null;
-    commit: string;
+    commit: string | null;
     detached: boolean;
     dirtyPaths: readonly string[];
     locked: boolean;
@@ -84,7 +88,7 @@ export interface DeveloperAgentGitInspection {
     concurrentChangeInspectionComplete: boolean;
     concurrentChanges: readonly DeveloperAgentConcurrentPathChange[];
     defaultBase?: {
-        commit: string;
+        commit: string | null;
         ref: string;
     };
     kind: 'developer-agent-git-inspection';

package/src/developer-agent/git-inspection.js

@@ -126,6 +126,18 @@ function assertDeveloperAgentReadOnlyGitInvocation(args) {
             '--short',
             'HEAD',
         ]) ||
+        (args.length === 5 &&
+            args[1] === 'symbolic-ref' &&
+            args[2] === '--quiet' &&
+            args[3] === '--no-recurse' &&
+            (args[4] === 'HEAD' ||
+                (args[4]?.startsWith('refs/') === true && safeRef(args[4])))) ||
+        (args.length === 5 &&
+            args[1] === 'show-ref' &&
+            args[2] === '--verify' &&
+            args[3] === '--quiet' &&
+            args[4]?.startsWith('refs/') === true &&
+            safeRef(args[4])) ||
         sameArgs(args, [
             NO_OPTIONAL_LOCKS,
             ...DISABLE_FS_MONITOR,
@@ -499,6 +511,41 @@ async function resolveCommit(git, ref, cwd) {
     ], { cwd });
     return requireCommit(result.stdout, `Git ref ${ref}`);
 }
+async function exactRefExists(git, ref, cwd) {
+    const result = await git.run([NO_OPTIONAL_LOCKS, 'show-ref', '--verify', '--quiet', ref], {
+        allowedExitCodes: [0, 1],
+        cwd,
+    });
+    if (result.stdout !== '' || result.stderr !== '') {
+        return fail('git-output-invalid', 'Git ref existence returned unexpected output.');
+    }
+    if (result.exitCode === 0)
+        return true;
+    // show-ref also reports a dangling symbolic ref as absent. Check the ref
+    // itself without following it before admitting absence. Corrupt object refs
+    // fail show-ref above; symbolic refs remain present and must resolve normally.
+    const symbolic = await git.run([NO_OPTIONAL_LOCKS, 'symbolic-ref', '--quiet', '--no-recurse', ref], { allowedExitCodes: [0, 1], cwd });
+    if (symbolic.stderr !== '' ||
+        (symbolic.exitCode === 1 && symbolic.stdout !== '')) {
+        return fail('git-output-invalid', 'Git symbolic ref existence returned unexpected output.');
+    }
+    if (symbolic.exitCode === 0) {
+        const target = singleSafeLine(symbolic.stdout, 'Git symbolic ref target');
+        if (!target.startsWith('refs/') || !safeRef(target)) {
+            return fail('git-output-invalid', 'Git symbolic ref target is invalid.');
+        }
+        return true;
+    }
+    return false;
+}
+async function resolveDefaultBase(git, ref, cwd, allowMissing) {
+    if (allowMissing &&
+        ref.startsWith('refs/') &&
+        !(await exactRefExists(git, ref, cwd))) {
+        return null;
+    }
+    return resolveCommit(git, ref, cwd);
+}
 async function resolveDirectory(git, kind, cwd) {
     const result = await git.run([NO_OPTIONAL_LOCKS, 'rev-parse', '--path-format=absolute', kind], { cwd });
     return requireAbsoluteDirectoryOutput(result.stdout, kind === '--show-toplevel' ? 'Git worktree root' : 'Git common directory', kind === '--show-toplevel'
@@ -521,16 +568,32 @@ async function resolveBranch(git, cwd) {
     }
     return { branch, detached: false };
 }
-async function verifyWorktree(git, commonDirectory, worktree, budget) {
+async function verifyWorktree(git, commonDirectory, worktree, budget, allowUnborn) {
     const discoveredRoot = await resolveDirectory(git, '--show-toplevel', worktree.realRoot);
     const discoveredCommon = await resolveDirectory(git, '--git-common-dir', worktree.realRoot);
     if (discoveredRoot !== worktree.realRoot ||
         discoveredCommon !== commonDirectory) {
         return fail('git-worktree-ambiguous', 'Linked worktree identity does not match the inspected repository.');
     }
-    const commit = await resolveCommit(git, 'HEAD', worktree.realRoot);
+    let commit;
+    if (allowUnborn && /^0{40}(?:0{24})?$/.test(worktree.head)) {
+        if (!worktree.branchRef || worktree.detached) {
+            return fail('git-output-invalid', 'Unborn worktree must have one symbolic local branch.');
+        }
+        const symbolic = await git.run([NO_OPTIONAL_LOCKS, 'symbolic-ref', '--quiet', '--no-recurse', 'HEAD'], { cwd: worktree.realRoot });
+        if (symbolic.stderr !== '' ||
+            singleSafeLine(symbolic.stdout, 'Unborn HEAD branch') !==
+                worktree.branchRef ||
+            (await exactRefExists(git, worktree.branchRef, worktree.realRoot))) {
+            return fail('git-worktree-ambiguous', 'Unborn HEAD does not match an absent exact local branch.');
+        }
+        commit = null;
+    }
+    else {
+        commit = await resolveCommit(git, 'HEAD', worktree.realRoot);
+    }
     const branchState = await resolveBranch(git, worktree.realRoot);
-    if (commit !== worktree.head ||
+    if ((commit !== null && commit !== worktree.head) ||
         branchState.branch !== worktree.branch ||
         branchState.detached !== worktree.detached) {
         return fail('git-worktree-ambiguous', 'Linked worktree state changed during inspection.');
@@ -555,7 +618,7 @@ async function verifyWorktree(git, commonDirectory, worktree, budget) {
     };
 }
 async function inspectUpstream(git, current) {
-    if (!current.branch)
+    if (!current.branch || current.commit === null)
         return undefined;
     const upstreamResult = await git.run([
         NO_OPTIONAL_LOCKS,
@@ -662,6 +725,10 @@ async function inspectConcurrentChanges(git, current, worktrees, budget) {
             continue;
         for (const path of worktree.dirtyPaths)
             record(path, worktree.root, 'dirty');
+        if (worktree.commit === null || current.commit === null) {
+            complete = false;
+            continue;
+        }
         if (worktree.commit === current.commit)
             continue;
         const mergeBase = await git.run([
@@ -723,6 +790,11 @@ function validateInput(options) {
     if ((options.base === undefined) !== (options.head === undefined)) {
         return fail('invalid-input', 'Git comparison requires both explicit base and head refs.');
     }
+    for (const value of [options.allowUnborn, options.allowMissingDefaultBase]) {
+        if (value !== undefined && typeof value !== 'boolean') {
+            return fail('invalid-input', 'Git orientation allowances must be explicit booleans.');
+        }
+    }
     if (options.base !== undefined && options.head !== undefined) {
         return {
             base: requireSafeRef(options.base, 'Git comparison base'),
@@ -754,7 +826,7 @@ async function inspectDeveloperAgentGit(options) {
     const budget = { count: 0 };
     const linkedWorktrees = [];
     for (const worktree of prepared) {
-        linkedWorktrees.push(await verifyWorktree(git, commonDirectory, worktree, budget));
+        linkedWorktrees.push(await verifyWorktree(git, commonDirectory, worktree, budget, options.allowUnborn === true));
     }
     const current = linkedWorktrees.find(({ root }) => root === currentRoot);
     if (!current) {
@@ -763,7 +835,7 @@ async function inspectDeveloperAgentGit(options) {
     const upstream = await inspectUpstream(git, current);
     const defaultBase = comparisonInput.defaultBase !== undefined
         ? {
-            commit: await resolveCommit(git, comparisonInput.defaultBase, currentRoot),
+            commit: await resolveDefaultBase(git, comparisonInput.defaultBase, currentRoot, options.allowMissingDefaultBase === true),
             ref: comparisonInput.defaultBase,
         }
         : undefined;

package/src/developer-agent/model.d.ts

@@ -159,10 +159,12 @@ export interface DeveloperAgentGitContext {
     baseCommit?: string;
     behind: number;
     branch?: string;
-    commit: string;
+    /** Null means a verified unborn symbolic branch, never a placeholder SHA. */
+    commit: string | null;
     concurrentChangeInspectionComplete: boolean;
     concurrentChanges: readonly DeveloperAgentConcurrentChangeContext[];
-    defaultBaseCommit: string;
+    /** An implicit base may be absent during local first-use orientation. */
+    defaultBaseCommit: string | null;
     defaultBaseRef: string;
     dirty: boolean;
     headCommit?: string;