@deftai/directive-core 0.106.0 → 0.108.0

package/dist/spec-authority/resolver.js

@@ -1,8 +1,8 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { resolveLifecycleLayout, resolveLifecycleRoot, resolveProjectDefinitionPath, } from "../layout/resolve.js";
-import { SPEC_RENDER_BANNER } from "../render/constants.js";
-import { contentHasGeneratedPdSource, contentHasGeneratedSpecSource, EXPORT_SPEC_PD_BANNER, GENERATED_SPEC_PURPOSE, } from "./constants.js";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { resolveLifecycleLayout, resolveLifecycleRoot, resolveProjectDefinitionPath, resolveSpecArtifactPath, } from "../layout/resolve.js";
+import { buildExportSpecPdBanner, buildGeneratedArtifactBanner, contentHasGeneratedPdSource, contentHasGeneratedSpecSource, GENERATED_SPEC_PURPOSE, generatedSpecSourcePaths, } from "./constants.js";
 export function resolveSpecAuthority(projectRoot) {
     const root = projectRoot;
     let layout;
@@ -20,13 +20,17 @@ export function resolveSpecAuthority(projectRoot) {
     const specPath = join(vbriefDir, `specification${layout.artifactSuffix}`);
     const hasSpec = existsSync(specPath);
     const kind = hasSpec ? "full-spec" : "greenfield";
-    const banner = kind === "full-spec" ? SPEC_RENDER_BANNER : EXPORT_SPEC_PD_BANNER;
+    const sourcePath = hasSpec ? specPath : projectDefPath;
+    const banner = hasSpec
+        ? buildGeneratedArtifactBanner("task spec:render", "rendered specification", sourcePath)
+        : buildExportSpecPdBanner(sourcePath);
     return {
         kind,
         projectRoot: root,
         vbriefDir,
         projectDefPath,
         specPath: hasSpec ? specPath : null,
+        sourcePath,
         banner,
     };
 }
@@ -39,12 +43,56 @@ export function readSpecMarkdown(projectRoot) {
         return "";
     }
 }
+function sourcePathFromMarker(projectRoot, source) {
+    return isAbsolute(source) ? source : resolve(projectRoot, source);
+}
+function contentMatchesResolvedSpecSource(projectRoot, content, resolvedSourcePath) {
+    if (contentHasGeneratedSpecSource(content, resolvedSourcePath))
+        return true;
+    let resolvedSource;
+    try {
+        resolvedSource = JSON.parse(readFileSync(resolvedSourcePath, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    for (const source of generatedSpecSourcePaths(content)) {
+        try {
+            const candidate = sourcePathFromMarker(projectRoot, source);
+            if (!statSync(candidate).isFile())
+                continue;
+            // Explicit --spec paths remain valid aliases only when they identify the
+            // same JSON authority as the layout-resolved specification artifact.
+            if (isDeepStrictEqual(JSON.parse(readFileSync(candidate, "utf8")), resolvedSource)) {
+                return true;
+            }
+        }
+        catch {
+            // Missing or unreadable explicit source markers are not resolved authority.
+        }
+    }
+    return false;
+}
+/** True when the markdown source marker resolves to the project's specification authority. */
+export function contentHasResolvedSpecSource(projectRoot, content) {
+    let resolvedSourcePath;
+    try {
+        resolvedSourcePath = resolveSpecArtifactPath(projectRoot);
+    }
+    catch {
+        return false;
+    }
+    if (!existsSync(resolvedSourcePath))
+        return false;
+    return contentMatchesResolvedSpecSource(projectRoot, content, resolvedSourcePath);
+}
 export function isFullSpecState(projectRoot) {
     const authority = resolveSpecAuthority(projectRoot);
     if (authority?.kind !== "full-spec")
         return false;
     const specMd = readSpecMarkdown(projectRoot);
-    return specMd.includes(GENERATED_SPEC_PURPOSE) && contentHasGeneratedSpecSource(specMd);
+    return (specMd.includes(GENERATED_SPEC_PURPOSE) &&
+        contentMatchesResolvedSpecSource(projectRoot, specMd, authority.sourcePath));
 }
 export function isGreenfieldSpecExport(projectRoot) {
     const authority = resolveSpecAuthority(projectRoot);

package/dist/subprocess/max-buffer.d.ts

@@ -15,4 +15,18 @@
  * so an overflow is never silent again.
  */
 export declare const SUBPROCESS_MAX_BUFFER: number;
+/**
+ * Reason text for a failed capture, so an overflow is never blank (#1867 / #3903).
+ *
+ * A spawn-level failure (ENOBUFS past the ceiling, timeout kill, missing
+ * binary) reports no exit status and empty stderr, whether it arrives as a
+ * `spawnSync` result or as a thrown `execFileSync` error. Only then does the
+ * error message stand in for stderr: a process that exited with a status and
+ * chose to say nothing keeps its empty stderr.
+ */
+export declare function resolveCaptureFailureStderr(capture: {
+    readonly captured: string;
+    readonly status: number | null | undefined;
+    readonly message: string | undefined;
+}): string;
 //# sourceMappingURL=max-buffer.d.ts.map

package/dist/subprocess/max-buffer.js

@@ -15,4 +15,19 @@
  * so an overflow is never silent again.
  */
 export const SUBPROCESS_MAX_BUFFER = 64 * 1024 * 1024;
+/**
+ * Reason text for a failed capture, so an overflow is never blank (#1867 / #3903).
+ *
+ * A spawn-level failure (ENOBUFS past the ceiling, timeout kill, missing
+ * binary) reports no exit status and empty stderr, whether it arrives as a
+ * `spawnSync` result or as a thrown `execFileSync` error. Only then does the
+ * error message stand in for stderr: a process that exited with a status and
+ * chose to say nothing keeps its empty stderr.
+ */
+export function resolveCaptureFailureStderr(capture) {
+    if (capture.captured.trim().length > 0 || typeof capture.status === "number") {
+        return capture.captured;
+    }
+    return capture.message ?? capture.captured;
+}
 //# sourceMappingURL=max-buffer.js.map

package/dist/swarm/complete-cohort.d.ts

@@ -47,6 +47,8 @@ export declare function completeCohort(args: {
     delivery?: CohortDeliveryContext | null;
     /** Optional launch allocation plan id so close-out reads this cohort's occupancy slot. */
     allocationPlanId?: string | null;
+    /** Test seam and explicit ambient-owner source for close-out corroboration. */
+    env?: NodeJS.ProcessEnv;
 }): {
     exitCode: number;
     stdout: string;

package/dist/swarm/complete-cohort.js

@@ -471,25 +471,33 @@ export function completeCohort(args) {
     });
     result.errors.push(...errors);
     if (result.ok && args.dryRun !== true) {
-        const envSession = process.env.DEFT_SESSION_ID?.trim() ?? "";
-        let sessionId = envSession;
-        if (sessionId.length === 0) {
-            const resolved = resolveLaunchOccupancySessionId(projectRoot, {
-                allocationPlanId: args.allocationPlanId ?? null,
-                storyIds: paths.map(storyIdFromPath),
-            });
-            if (resolved.reason === "ok" && resolved.sessionId.length > 0) {
-                sessionId = resolved.sessionId;
-            }
-            else if (readOccupancy(projectRoot) !== null) {
+        const env = args.env ?? process.env;
+        const envSession = env.DEFT_SESSION_ID?.trim() ?? "";
+        const liveOccupancy = readOccupancy(projectRoot);
+        const resolved = resolveLaunchOccupancySessionId(projectRoot, {
+            allocationPlanId: args.allocationPlanId ?? null,
+            storyIds: paths.map(storyIdFromPath),
+        });
+        let sessionId = "";
+        if (liveOccupancy !== null) {
+            if (resolved.reason !== "ok" || resolved.sessionId.length === 0) {
                 result.ok = false;
                 result.errors.push("swarm close-out occupancy record is missing or belongs to a different cohort. " +
-                    "Steal with occupancy:steal --confirm --occupant <id>.");
+                    "Re-establish an aligned owner with session:start --steal --confirm " +
+                    "--occupant <reported-session-id> --session-id=<your-session-id>.");
+            }
+            else if (envSession.length > 0 && envSession !== resolved.sessionId) {
+                result.ok = false;
+                result.errors.push(`swarm close-out ambient owner ${envSession} conflicts with cohort owner ` +
+                    `${resolved.sessionId}; refusing to release a later session's live lease.`);
+            }
+            else {
+                sessionId = resolved.sessionId;
             }
         }
         if (result.ok && sessionId.length > 0) {
             const released = releaseSwarmOccupancy(projectRoot, {
-                env: process.env,
+                env,
                 sessionId,
             });
             if (released.code !== 0) {

package/dist/swarm/index.d.ts

@@ -14,6 +14,7 @@ export { routingSetMain } from "./routing-set-cli.js";
 export * from "./routing-verify.js";
 export { routingVerifyMain } from "./routing-verify-cli.js";
 export * from "./subagent-backend.js";
+export * from "./subagent-status-dir.js";
 export * from "./subprocess.js";
 export * from "./verify-review-clean.js";
 export { verifyReviewCleanMain } from "./verify-review-clean-cli.js";

package/dist/swarm/index.js

@@ -14,6 +14,7 @@ export { routingSetMain } from "./routing-set-cli.js";
 export * from "./routing-verify.js";
 export { routingVerifyMain } from "./routing-verify-cli.js";
 export * from "./subagent-backend.js";
+export * from "./subagent-status-dir.js";
 export * from "./subprocess.js";
 export * from "./verify-review-clean.js";
 export { verifyReviewCleanMain } from "./verify-review-clean-cli.js";

package/dist/swarm/launch-cli.js

@@ -17,54 +17,58 @@ export function parseLaunchArgv(argv) {
     let enforceGatesFlag = false;
     let noAudit = false;
     let projectRoot = ".";
+    let sessionId = null;
+    let parseError = null;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
-        const next = argv[i + 1];
-        if (arg === "--stories" && next !== undefined) {
-            stories.push(next);
+        const takeValue = () => {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                parseError ??= `argument ${arg}: expected one argument`;
+                return null;
+            }
             i += 1;
+            return value;
+        };
+        if (arg === "--stories") {
+            const value = takeValue();
+            if (value !== null)
+                stories.push(value);
         }
-        else if (arg === "--paths" && next !== undefined) {
-            paths.push(next);
-            i += 1;
+        else if (arg === "--paths") {
+            const value = takeValue();
+            if (value !== null)
+                paths.push(value);
         }
-        else if (arg === "--group" && next !== undefined) {
-            group = next;
-            i += 1;
+        else if (arg === "--group") {
+            group = takeValue();
         }
-        else if (arg === "--worktree-map" && next !== undefined) {
-            worktreeMap = next;
-            i += 1;
+        else if (arg === "--worktree-map") {
+            worktreeMap = takeValue();
         }
-        else if (arg === "--base-branch" && next !== undefined) {
-            baseBranch = next;
-            i += 1;
+        else if (arg === "--base-branch") {
+            baseBranch = takeValue() ?? baseBranch;
         }
         else if (arg === "--autonomous") {
             autonomous = true;
         }
-        else if (arg === "--allocation-plan-id" && next !== undefined) {
-            allocationPlanId = next;
-            i += 1;
+        else if (arg === "--allocation-plan-id") {
+            allocationPlanId = takeValue();
         }
-        else if (arg === "--batching-rationale" && next !== undefined) {
-            batchingRationale = next;
-            i += 1;
+        else if (arg === "--batching-rationale") {
+            batchingRationale = takeValue();
         }
-        else if (arg === "--operator-approval" && next !== undefined) {
-            operatorApproval = next;
-            i += 1;
+        else if (arg === "--operator-approval") {
+            operatorApproval = takeValue();
         }
         else if (arg === "--no-create-worktrees") {
             noCreateWorktrees = true;
         }
-        else if (arg === "--output" && next !== undefined) {
-            output = next;
-            i += 1;
+        else if (arg === "--output") {
+            output = takeValue();
         }
-        else if (arg === "--gate-clearances" && next !== undefined) {
-            gateClearancesPath = next;
-            i += 1;
+        else if (arg === "--gate-clearances") {
+            gateClearancesPath = takeValue();
         }
         else if (arg === "--enforce-gates") {
             enforceGatesFlag = true;
@@ -72,12 +76,27 @@ export function parseLaunchArgv(argv) {
         else if (arg === "--no-audit") {
             noAudit = true;
         }
-        else if (arg === "--project-root" && next !== undefined) {
-            projectRoot = next;
-            i += 1;
+        else if (arg === "--project-root") {
+            projectRoot = takeValue() ?? projectRoot;
+        }
+        else if (arg === "--session-id") {
+            const value = takeValue();
+            if (value === null) {
+                // Keep an explicit invalid sentinel so swarmLaunch fails closed rather
+                // than falling back to ambient identity or minting a different owner.
+                sessionId = "";
+            }
+            else {
+                sessionId = value;
+            }
+        }
+        else if (arg?.startsWith("--session-id=") === true) {
+            const value = arg.slice("--session-id=".length);
+            sessionId = value.startsWith("--") ? "" : value;
         }
     }
     return {
+        parseError,
         stories,
         paths,
         group,
@@ -93,6 +112,7 @@ export function parseLaunchArgv(argv) {
         enforceGatesFlag,
         noAudit,
         projectRoot,
+        sessionId,
     };
 }
 export function launchMain(argv = process.argv.slice(2)) {

package/dist/swarm/launch.d.ts

@@ -1,3 +1,5 @@
+import { type ExpectedGithubWorkerPrincipal, type GhRunner, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN } from "../intake/github-auth-modes.js";
+import { releaseOccupancy } from "../session/occupancy.js";
 import { EXIT_CONFIG_ERROR, EXIT_GATE_FAILED, EXIT_OK } from "./constants.js";
 import { type WorktreeRecord } from "./worktrees.js";
 export interface ResolvedStory {
@@ -18,9 +20,74 @@ export type WorktreeResolverFn = (mapping: readonly Record<string, unknown>[], b
     repoRoot?: string;
 }) => WorktreeRecord[];
 export type RuntimeAuthProbeFn = () => [string, string];
+export type OccupancyReleaseFn = typeof releaseOccupancy;
 export declare const defaultPreflightGate: PreflightGateFn;
 export declare const defaultReadinessGate: ReadinessGateFn;
 export declare const defaultRuntimeAuthProbe: RuntimeAuthProbeFn;
+export type WorkerCredentialDispatchPath = "grok-build" | "local-hybrid";
+/**
+ * Dispatch-envelope half of the runtime / GitHub auth-mode contract (#1557 / #1351).
+ * Policy labels only — never a token value.
+ */
+export declare function formatDispatchAuthEnvelope(fields: {
+    runtimeMode: string;
+    githubAuthMode: string;
+    expectedGithubLogin?: string | null;
+}): string;
+export interface WorkerCredentialInjectionRequest {
+    environ?: NodeJS.ProcessEnv;
+    githubAuthMode: string;
+    runtimeMode?: string | null;
+    dispatchPath?: WorkerCredentialDispatchPath;
+    expectedPrincipal?: ExpectedGithubWorkerPrincipal | null;
+    repo?: string;
+    runGh?: GhRunner;
+    cwd?: string;
+}
+export type WorkerCredentialInjectionResult = {
+    ok: true;
+    injected: true;
+    githubAuthMode: typeof GITHUB_AUTH_MODE_INJECTED_TOKEN;
+    runtimeMode: string | null;
+    expectedLogin: string;
+    spawnEnv: {
+        GH_TOKEN: string;
+        GITHUB_TOKEN: string;
+        GH_ENTERPRISE_TOKEN: string;
+        DEFT_EXPECTED_GITHUB_LOGIN: string;
+    };
+    envelopeSection: string;
+} | {
+    ok: true;
+    injected: false;
+    githubAuthMode: typeof GITHUB_AUTH_MODE_HOST_GH;
+    runtimeMode: string | null;
+    expectedLogin: string | null;
+    spawnEnv: Record<string, never>;
+    envelopeSection: string;
+} | {
+    ok: false;
+    blocked: true;
+    githubAuthMode: string;
+    runtimeMode: string | null;
+    missingCredential: string;
+    remedy: string;
+    detail: string;
+    failureKind: string | null;
+    envelopeSection: string;
+};
+/**
+ * Validate a held user-bearing worker credential and prepare spawn-time injection (#1351).
+ *
+ * Comparison is opt-in on the validator. This path always stamps
+ * `DEFT_EXPECTED_GITHUB_LOGIN` after a successful user-principal check so the
+ * worker envelope does not inherit "any user token is approved."
+ *
+ * Installation credentials fail closed via the existing validator (#3693).
+ * Token values belong only in the returned `spawnEnv` — never in prompts,
+ * transcripts, or manifest entries.
+ */
+export declare function prepareWorkerCredentialInjection(request: WorkerCredentialInjectionRequest): WorkerCredentialInjectionResult;
 /**
  * True when a brief in `xbrief/completed/` (or the legacy `vbrief/completed/`)
  * references the given issue number in its `references[]` / `Traces`. Used by
@@ -74,10 +141,13 @@ export declare function buildManifest(resolved: readonly ResolvedStory[], option
     modelSource?: string | null;
     runtimeMode?: string | null;
     githubAuthMode?: string | null;
+    expectedGithubLogin?: string | null;
     occupancySessionId?: string | null;
 }): Record<string, unknown>[];
 export declare function orderCohort(resolved: readonly ResolvedStory[], _projectRoot: string): ResolvedStory[];
 export interface LaunchArgs {
+    /** CLI parse failure carried into the core so later valid flags cannot erase it. */
+    parseError?: string | null;
     stories?: readonly string[];
     paths?: readonly string[];
     group?: string | null;
@@ -93,16 +163,23 @@ export interface LaunchArgs {
     enforceGatesFlag?: boolean;
     noAudit?: boolean;
     projectRoot?: string;
+    /** Explicit cooperative owner identity, including host-payload canonical IDs (#3611). */
+    sessionId?: string | null;
     preflightGate?: PreflightGateFn;
     readinessGate?: ReadinessGateFn;
     worktreeResolver?: WorktreeResolverFn;
     runtimeAuthProbe?: RuntimeAuthProbeFn;
+    /** Test seam: override occupancy release after a newly minted claim fails. */
+    releaseOccupancyFn?: OccupancyReleaseFn;
     /**
      * Injection seam for the routing-provider environment lookup, mirroring
      * `resolveRoutingPath`'s `environ` parameter (#1877 Greptile follow-up).
      * Defaults to `process.env` when unset.
      */
     environ?: NodeJS.ProcessEnv;
+    /** Optional gh runner for identity-bound credential injection (#1351). */
+    runGh?: GhRunner;
+    expectedPrincipal?: ExpectedGithubWorkerPrincipal | null;
 }
 export declare function swarmLaunch(args: LaunchArgs): {
     exitCode: number;