@deftai/directive 0.107.0 → 0.108.0

package/dist/dispatch.d.ts

@@ -10,7 +10,7 @@ export interface DispatchIo {
     writeErr: (text: string) => void;
 }
 /** CLI modules in packages/cli/src (excluding parity harnesses and bin/index). */
-export declare const CLI_MODULE_VERBS: readonly ["agents-refresh", "cache", "check", "capacity-backfill", "capacity-show", "codebase-default-extractor", "codebase-map", "codebase-map-fresh", "codebase-projection-registry", "codebase-provider", "doctor", "install-upgrade", "install-uninstall", "migrate-preflight", "migrate-xbrief", "migrate-category-b", "framework-check-updates", "hook-dispatch", "umbrella-current-shape", "changelog-check", "change-init", "commit-lint", "coverage-hotspots", "policy", "authz", "escalation-cli", "pr-closing-keywords", "pr-merge-readiness", "pr-monitor", "pr-protected-issues", "pr-wait-mergeable", "pr-watch", "pr-finish-loop", "directive-finish-loop", "preflight-cache", "preflight-gh", "probe-session", "release", "release-e2e", "release-publish", "release-rollback", "scope-lifecycle", "scope-record-approved-scope", "scm-sync-default", "lifecycle-event", "lifecycle-stats", "session-start", "session-ready", "occupancy-steal", "occupancy-release", "plan-sequence", "slice", "subagent-monitor", "toolchain-check", "triage-actions", "triage-bootstrap", "triage-bulk", "triage-classify", "triage-evaluate", "triage-help", "triage-queue", "triage-reconcile", "triage-refresh", "triage-scope", "triage-scope-drift", "triage-smoketest", "triage-subscribe", "triage-summary", "triage-welcome", "ts-check-lane", "vbrief-activate", "vbrief-build", "vbrief-preflight", "vbrief-reconcile", "vbrief-validate", "vbrief-validation", "xbrief-create", "xbrief-verify", "verify-branch", "verify-encoding", "verify-forward-coverage", "verify-test-boundary", "verify-scope-provenance", "verify-consumer-check-contract", "verify-hooks-installed", "verify-investigation", "verify-judgment-gates", "verify-no-task-runtime", "validate-links", "validate-strategy-output", "verify-biome-config", "verify-bridge-drift", "verify-capacity", "verify-contained-writes", "verify-telemetry-coverage", "verify-content-manifest", "verify-skill-external-fetch-gate", "verify-contract-drift", "verify-cursor-tier1", "verify-openclaw-tier1", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-plan-sequence", "verify-stubs", "verify-xbrief-drift", "rule-ownership-lint", "verify-story-ready", "verify-review-monitor", "verify-l4-owner", "verify-subagent-alive", "review-monitor-register", "review-monitor-release", "verify-tools", "verify-wip-cap", "verify-orphan-active", "verify-lifecycle-visible", "verify-completed-tracked", "verify-completed-write-guard", "verify-literal-ac", "verify-ac", "verify-agents-md-budget", "verify-agents-md-advisory", "verify-eval-health-relocation", "verify-eval-triggers-relocation", "eval-health", "eval-run", "eval-report", "eval-triggers"];
+export declare const CLI_MODULE_VERBS: readonly ["agents-refresh", "cache", "check", "capacity-backfill", "capacity-show", "codebase-default-extractor", "codebase-map", "codebase-map-fresh", "codebase-projection-registry", "codebase-provider", "doctor", "install-upgrade", "install-uninstall", "migrate-preflight", "migrate-xbrief", "migrate-category-b", "framework-check-updates", "hook-dispatch", "umbrella-current-shape", "changelog-check", "change-init", "commit-lint", "coverage-hotspots", "policy", "authz", "escalation-cli", "pr-closing-keywords", "pr-merge-readiness", "pr-monitor", "pr-protected-issues", "pr-wait-mergeable", "pr-watch", "pr-finish-loop", "directive-finish-loop", "preflight-cache", "preflight-gh", "probe-session", "release", "release-e2e", "release-publish", "release-rollback", "scope-lifecycle", "scope-record-approved-scope", "scm-sync-default", "lifecycle-event", "lifecycle-stats", "session-start", "session-ready", "occupancy-steal", "occupancy-release", "occupancy-heartbeat", "occupancy-grant", "plan-sequence", "slice", "subagent-monitor", "toolchain-check", "triage-actions", "triage-bootstrap", "triage-bulk", "triage-classify", "triage-evaluate", "triage-help", "triage-queue", "triage-reconcile", "triage-refresh", "triage-scope", "triage-scope-drift", "triage-smoketest", "triage-subscribe", "triage-summary", "triage-welcome", "ts-check-lane", "vbrief-activate", "vbrief-build", "vbrief-preflight", "vbrief-reconcile", "vbrief-validate", "vbrief-validation", "xbrief-create", "xbrief-verify", "verify-branch", "verify-encoding", "verify-forward-coverage", "verify-test-boundary", "verify-scope-provenance", "verify-consumer-check-contract", "verify-hooks-installed", "verify-investigation", "verify-judgment-gates", "verify-no-task-runtime", "validate-links", "validate-strategy-output", "verify-biome-config", "verify-bridge-drift", "verify-capacity", "verify-contained-writes", "verify-telemetry-coverage", "verify-content-manifest", "verify-skill-external-fetch-gate", "verify-contract-drift", "verify-cursor-tier1", "verify-openclaw-tier1", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-plan-sequence", "verify-stubs", "verify-xbrief-drift", "rule-ownership-lint", "verify-story-ready", "verify-review-monitor", "verify-l4-owner", "verify-subagent-alive", "review-monitor-register", "review-monitor-release", "verify-tools", "verify-wip-cap", "verify-orphan-active", "verify-pr-closeout-attestable", "verify-lifecycle-visible", "verify-completed-tracked", "verify-completed-write-guard", "verify-literal-ac", "verify-ac", "verify-agents-md-budget", "verify-agents-md-advisory", "verify-eval-health-relocation", "verify-eval-triggers-relocation", "eval-health", "eval-run", "eval-report", "eval-triggers"];
 /** Core-only CLI entrypoints without a packages/cli wrapper. */
 export declare const CORE_MODULE_VERBS: readonly ["scm", "scm-readiness", "github-auth-modes", "github-body", "issue-emit", "issue-ingest", "issue-sync-from-xbrief", "reconcile-issues", "swarm-launch", "swarm-complete-cohort", "swarm-finalize-cohort", "swarm-pre-dispatch", "swarm-readiness", "swarm-routing-verify", "swarm-routing-set", "swarm-verify-review-clean", "swarm-worktrees", "framework-commands", "pack-render", "packs-slice", "prd-render", "export-spec", "project-render", "roadmap-render", "rule-map", "spec-render", "spec-validate", "code-structure-validate", "pack-migrate-skills", "pack-migrate-rules", "pack-migrate-strategies", "pack-migrate-patterns", "pack-migrate-swarm-spec", "policy-set", "setup-ghx", "scope-undo", "scope-demote", "scope-decompose", "changelog-resolve-unreleased", "architecture-preflight-sor", "feedback-file", "value-readback", "product-signal", "freshness-report", "decision-write", "decision-list"];
 /** Colon aliases for triage-actions (mirrors cli-router SUBCOMMAND_ROUTES). */

package/dist/dispatch.js

@@ -8,12 +8,11 @@ import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readSync
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { engineInfo, userConfig } from "@deftai/directive-core";
-import { assertWriteTargetSafe } from "@deftai/directive-core/dist/fs/projection-containment.js";
 import { parseInitArgv, runInitDepositCli } from "@deftai/directive-core/init-deposit";
 import { appendAuditLog, disclosureLine, migrateLegacyPolicyKey, PLAN_POLICY_KEY, POLICY_AUDIT_NOOP_STDOUT, policyColonInvocation, policySetInvocation, projectDefinitionPath, resolvePolicy, resolveWipCap, setPolicy, stampChangedToken, } from "@deftai/directive-core/policy";
 import { defaultWhich } from "@deftai/directive-core/scm";
 import { KNOWN_SUBAGENT_BACKEND_IDS, probeSubagentBackends, resolveSwarmSubagentBackend, } from "@deftai/directive-core/swarm";
-import { atomicWriteProjectDefinition } from "@deftai/directive-core/vbrief-build";
+import { withProjectDefinitionMutation, } from "@deftai/directive-core/vbrief-build";
 const HANDLER_KEYS = [
     "run",
     "main",
@@ -76,6 +75,8 @@ export const CLI_MODULE_VERBS = [
     "session-ready",
     "occupancy-steal",
     "occupancy-release",
+    "occupancy-heartbeat",
+    "occupancy-grant",
     "plan-sequence",
     "slice",
     "subagent-monitor",
@@ -142,6 +143,7 @@ export const CLI_MODULE_VERBS = [
     "verify-tools",
     "verify-wip-cap",
     "verify-orphan-active",
+    "verify-pr-closeout-attestable",
     "verify-lifecycle-visible",
     "verify-completed-tracked",
     "verify-completed-write-guard",
@@ -287,6 +289,7 @@ export const VERB_ALIASES = {
     "verify:vbrief-conformance": "vbrief-validate",
     "verify:wip-cap": "verify-wip-cap",
     "verify:orphan-active": "verify-orphan-active",
+    "verify:pr-closeout-attestable": "verify-pr-closeout-attestable",
     "verify:lifecycle-visible": "verify-lifecycle-visible",
     "verify:completed-tracked": "verify-completed-tracked",
     "verify:completed-write-guard": "verify-completed-write-guard",
@@ -369,6 +372,8 @@ export const VERB_ALIASES = {
     "session:ready": "session-ready",
     "occupancy:steal": "occupancy-steal",
     "occupancy:release": "occupancy-release",
+    "occupancy:heartbeat": "occupancy-heartbeat",
+    "occupancy:grant": "occupancy-grant",
     "session:end": "occupancy-release",
     ...FRESHNESS_COLON_ALIASES,
     "lifecycle:event": "lifecycle-event",
@@ -2104,25 +2109,26 @@ function parsePolicySetArgs(argv) {
     }
     return args;
 }
-/** Load PROJECT-DEFINITION for an in-place typed-field write (mirrors the .setdefault chain). */
-function loadProjectDefinitionForWrite(projectRoot) {
-    const path = projectDefinitionPath(projectRoot);
+/**
+ * Load PROJECT-DEFINITION for an in-place typed-field write (mirrors the
+ * .setdefault chain). Reads the artifact the mutation lock captured (#3796) so
+ * these CLI writers can no longer resolve, read, and write a PROJECT-DEFINITION
+ * outside the shared mutation lock.
+ */
+function loadProjectDefinitionForWrite(mutation) {
+    const path = mutation.artifactPath;
     if (!existsSync(path)) {
-        throw new PolicySetError(`PROJECT-DEFINITION not found at ${path}`, "not-found");
+        throw new PolicySetError(`PROJECT-DEFINITION not found at ${mutation.artifactLabel}`, "not-found");
     }
-    let parsed;
+    let data;
     try {
-        parsed = JSON.parse(readFileSync(path, "utf8"));
+        // The shared loader rejects unreadable, malformed, and non-object top-level
+        // payloads; every one of those is a config error for the CLI writers.
+        data = mutation.load();
     }
     catch (err) {
-        throw new PolicySetError(`PROJECT-DEFINITION at ${path} is not valid JSON: ${String(err)}`, "config");
+        throw new PolicySetError(err instanceof Error ? err.message : String(err), "config");
     }
-    // JSON.parse can yield a non-object top level (null / array / scalar) without
-    // throwing; reject it before the .plan/.policy property chain dereferences it.
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new PolicySetError(`PROJECT-DEFINITION at ${path} is not a JSON object`, "config");
-    }
-    const data = parsed;
     let plan = data.plan;
     if (plan === undefined) {
         plan = {};
@@ -2141,45 +2147,47 @@ function loadProjectDefinitionForWrite(projectRoot) {
     if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
         throw new PolicySetError("plan.policy is not an object", "config");
     }
-    return { path, data, policyBlock: policy, legacyMigrated };
+    return { data, policyBlock: policy, legacyMigrated };
 }
 /** Write plan.policy.wipCap in place + append the audit row (mirrors set_wip_cap). */
 function writeWipCap(projectRoot, cap, actor, note) {
-    const { path, data, policyBlock, legacyMigrated } = loadProjectDefinitionForWrite(projectRoot);
-    const previous = policyBlock.wipCap;
-    policyBlock.wipCap = cap;
-    const changed = previous !== cap || legacyMigrated;
-    const parts = [`actor=${actor}`, `wipCap=${cap}`, `previous=${pyRepr(previous)}`];
-    if (note)
-        parts.push(`note=${sanitizeNote(note)}`);
-    const auditEntry = stampChangedToken(parts.join(" "), changed);
-    if (changed) {
-        assertWriteTargetSafe(projectRoot, path);
-        atomicWriteProjectDefinition(path, data);
-    }
-    appendAuditLog(projectRoot, auditEntry, changed);
-    return { changed, auditEntry };
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const { data, policyBlock, legacyMigrated } = loadProjectDefinitionForWrite(mutation);
+        const previous = policyBlock.wipCap;
+        policyBlock.wipCap = cap;
+        const changed = previous !== cap || legacyMigrated;
+        const parts = [`actor=${actor}`, `wipCap=${cap}`, `previous=${pyRepr(previous)}`];
+        if (note)
+            parts.push(`note=${sanitizeNote(note)}`);
+        const auditEntry = stampChangedToken(parts.join(" "), changed);
+        if (changed) {
+            mutation.persist(data);
+        }
+        appendAuditLog(projectRoot, auditEntry, changed);
+        return { changed, auditEntry };
+    });
 }
 /** Write plan.policy.swarmSubagentBackend in place + append the audit row. */
 function writeSubagentBackend(projectRoot, backendId, actor, note) {
-    const { path, data, policyBlock, legacyMigrated } = loadProjectDefinitionForWrite(projectRoot);
-    const previous = policyBlock.swarmSubagentBackend;
-    policyBlock.swarmSubagentBackend = backendId;
-    const changed = previous !== backendId || legacyMigrated;
-    const parts = [
-        `actor=${actor}`,
-        `swarmSubagentBackend=${backendId}`,
-        `previous=${pyRepr(previous)}`,
-    ];
-    if (note)
-        parts.push(`note=${sanitizeNote(note)}`);
-    const auditEntry = stampChangedToken(parts.join(" "), changed);
-    if (changed) {
-        assertWriteTargetSafe(projectRoot, path);
-        atomicWriteProjectDefinition(path, data);
-    }
-    appendAuditLog(projectRoot, auditEntry, changed);
-    return { changed, auditEntry };
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const { data, policyBlock, legacyMigrated } = loadProjectDefinitionForWrite(mutation);
+        const previous = policyBlock.swarmSubagentBackend;
+        policyBlock.swarmSubagentBackend = backendId;
+        const changed = previous !== backendId || legacyMigrated;
+        const parts = [
+            `actor=${actor}`,
+            `swarmSubagentBackend=${backendId}`,
+            `previous=${pyRepr(previous)}`,
+        ];
+        if (note)
+            parts.push(`note=${sanitizeNote(note)}`);
+        const auditEntry = stampChangedToken(parts.join(" "), changed);
+        if (changed) {
+            mutation.persist(data);
+        }
+        appendAuditLog(projectRoot, auditEntry, changed);
+        return { changed, auditEntry };
+    });
 }
 /** Serialise the probe output for `subagent-backends --format json`. */
 function subagentBackendsToJson(backends) {
@@ -2617,19 +2625,30 @@ const CURATED_HELP_GROUPS = [
     {
         title: "Session & ritual",
         commands: [
-            { name: "session:start", summary: "Record session-start ritual state" },
+            {
+                name: "session:start",
+                summary: "Claim occupancy and record ritual state for one session owner",
+            },
             {
                 name: "session:ready",
                 summary: "One-shot recovery to gated write-ready (session + ritual + cache)",
             },
             {
                 name: "occupancy:steal",
-                summary: "Supersede a live worktree occupancy lease (--confirm --occupant)",
+                summary: "Replace only the live lease; use session:start --steal to align ritual",
             },
             {
                 name: "occupancy:release",
                 summary: "Release this worktree occupancy lease (owner live, or expired residue)",
             },
+            {
+                name: "occupancy:heartbeat",
+                summary: "Refresh your own live lease during long quiet stretches (never claims)",
+            },
+            {
+                name: "occupancy:grant",
+                summary: "Admit a dispatched child to your lease for writes (--revoke withdraws)",
+            },
             {
                 name: "session:end",
                 summary: "End this mutation session by releasing occupancy (same as occupancy:release)",
@@ -2795,6 +2814,9 @@ export async function dispatch(argv, io = defaultIo()) {
         const planSequenceSubcommand = verb !== undefined ? PLAN_SEQUENCE_ALIAS_SUBCOMMANDS[verb] : undefined;
         const productSignalSubcommand = verb !== undefined ? PRODUCT_SIGNAL_ALIAS_SUBCOMMANDS[verb] : undefined;
         const freshnessSubcommand = verb !== undefined ? FRESHNESS_ALIAS_SUBCOMMANDS[verb] : undefined;
+        const vbriefValidateSubcommand = verb === "verify:vbrief-conformance" && canonical === "vbrief-validate"
+            ? "conformance"
+            : undefined;
         const handlerArgv = canonical === "framework-commands" && verb !== undefined && verb !== canonical
             ? [verb, ...rest]
             : triageSubcommand !== undefined && canonical === "triage-actions"
@@ -2811,7 +2833,9 @@ export async function dispatch(argv, io = defaultIo()) {
                                     ? [productSignalSubcommand, ...rest]
                                     : freshnessSubcommand !== undefined && canonical === "freshness-report"
                                         ? [freshnessSubcommand, ...rest]
-                                        : rest;
+                                        : vbriefValidateSubcommand !== undefined
+                                            ? [vbriefValidateSubcommand, ...rest]
+                                            : rest;
         return await invokeHandler(handler, handlerArgv);
     }
     catch (err) {

package/dist/occupancy-grant.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { type OccupancyJoinProtocol } from "@deftai/directive-core/session";
+export interface GrantArgs {
+    projectRoot: string;
+    sessionId?: string;
+    childSessionId?: string;
+    role?: string;
+    worktree?: string;
+    ttlMinutes?: number;
+    host?: string;
+    address?: string;
+    joinProtocol?: OccupancyJoinProtocol;
+    revoke: boolean;
+    error?: string;
+}
+export declare function parseArgs(argv: readonly string[]): GrantArgs;
+export declare function run(argv: readonly string[]): number;
+//# sourceMappingURL=occupancy-grant.d.ts.map

package/dist/occupancy-grant.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { grantOccupancyMembership, OCCUPANCY_JOIN_PROTOCOLS, revokeOccupancyMembership, } from "@deftai/directive-core/session";
+const VALUE_FLAGS = [
+    "--project-root",
+    "--session-id",
+    "--child-session-id",
+    "--role",
+    "--worktree",
+    "--ttl-minutes",
+    "--host",
+    "--address",
+    "--join-protocol",
+];
+function readValue(argv, index, flag) {
+    const arg = argv[index] ?? "";
+    const inline = `${flag}=`;
+    const raw = arg.startsWith(inline) ? arg.slice(inline.length) : argv[index + 1];
+    if (raw === undefined || raw.startsWith("--")) {
+        return { error: `argument ${flag}: expected one argument` };
+    }
+    const value = raw.trim();
+    if (value.length === 0) {
+        return { error: `argument ${flag}: expected a non-empty value` };
+    }
+    return { value, next: arg.startsWith(inline) ? index : index + 1 };
+}
+export function parseArgs(argv) {
+    const parsed = { projectRoot: ".", revoke: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i] ?? "";
+        if (arg === "--revoke")
+            continue;
+        const flag = VALUE_FLAGS.find((name) => arg === name || arg.startsWith(`${name}=`));
+        if (flag === undefined) {
+            return {
+                ...parsed,
+                revoke: argv.includes("--revoke"),
+                error: `unrecognized argument: ${arg}`,
+            };
+        }
+        const read = readValue(argv, i, flag);
+        if ("error" in read)
+            return { ...parsed, revoke: argv.includes("--revoke"), error: read.error };
+        i = read.next;
+        switch (flag) {
+            case "--project-root":
+                parsed.projectRoot = read.value;
+                break;
+            case "--session-id":
+                parsed.sessionId = read.value;
+                break;
+            case "--child-session-id":
+                parsed.childSessionId = read.value;
+                break;
+            case "--role":
+                parsed.role = read.value;
+                break;
+            case "--worktree":
+                parsed.worktree = read.value;
+                break;
+            case "--host":
+                parsed.host = read.value;
+                break;
+            case "--address":
+                parsed.address = read.value;
+                break;
+            case "--ttl-minutes": {
+                const minutes = Number(read.value);
+                if (!Number.isFinite(minutes) || minutes <= 0) {
+                    return {
+                        ...parsed,
+                        revoke: argv.includes("--revoke"),
+                        error: "argument --ttl-minutes: expected a positive number of minutes",
+                    };
+                }
+                parsed.ttlMinutes = minutes;
+                break;
+            }
+            case "--join-protocol": {
+                if (!OCCUPANCY_JOIN_PROTOCOLS.includes(read.value)) {
+                    return {
+                        ...parsed,
+                        revoke: argv.includes("--revoke"),
+                        error: `argument --join-protocol: expected one of ${OCCUPANCY_JOIN_PROTOCOLS.join(", ")}`,
+                    };
+                }
+                parsed.joinProtocol = read.value;
+                break;
+            }
+        }
+    }
+    return { ...parsed, revoke: argv.includes("--revoke") };
+}
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`occupancy:grant: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const input = {
+        sessionId: args.sessionId,
+        childSessionId: args.childSessionId,
+        role: args.role,
+        worktreePath: args.worktree,
+        ttlMs: args.ttlMinutes === undefined ? undefined : args.ttlMinutes * 60 * 1000,
+        host: args.host,
+        address: args.address,
+        joinProtocol: args.joinProtocol,
+        env: process.env,
+    };
+    const result = args.revoke
+        ? revokeOccupancyMembership(projectRoot, input)
+        : grantOccupancyMembership(projectRoot, input);
+    const sink = result.code === 0 ? process.stdout : process.stderr;
+    sink.write(`${result.message}\n`);
+    return result.code;
+}
+//# sourceMappingURL=occupancy-grant.js.map

package/dist/occupancy-heartbeat.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export declare function parseArgs(argv: readonly string[]): {
+    projectRoot: string;
+    sessionId?: string;
+    error?: string;
+};
+export declare function run(argv: readonly string[]): number;
+//# sourceMappingURL=occupancy-heartbeat.d.ts.map

package/dist/occupancy-heartbeat.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { heartbeatOccupancy } from "@deftai/directive-core/session";
+export function parseArgs(argv) {
+    const parsed = { projectRoot: "." };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            const value = arg.slice("--project-root=".length);
+            if (value.length === 0 || value.startsWith("--")) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+        }
+        else if (arg === "--session-id") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected one argument" };
+            }
+            const sessionId = value.trim();
+            if (sessionId.length === 0 || sessionId.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected a non-empty value" };
+            }
+            parsed.sessionId = sessionId;
+            i += 1;
+        }
+        else if (arg?.startsWith("--session-id=")) {
+            const sessionId = arg.slice("--session-id=".length).trim();
+            if (sessionId.length === 0 || sessionId.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected a non-empty value" };
+            }
+            parsed.sessionId = sessionId;
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`occupancy:heartbeat: ${args.error}\n`);
+        return 2;
+    }
+    const result = heartbeatOccupancy(resolve(args.projectRoot), {
+        sessionId: args.sessionId,
+        env: process.env,
+    });
+    const sink = result.code === 0 ? process.stdout : process.stderr;
+    sink.write(`${result.message}\n`);
+    return result.code;
+}
+//# sourceMappingURL=occupancy-heartbeat.js.map

package/dist/occupancy-release.d.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 export declare function parseArgs(argv: readonly string[]): {
     projectRoot: string;
+    sessionId?: string;
     error?: string;
 };
 export declare function run(argv: readonly string[]): number;

package/dist/occupancy-release.js

@@ -7,14 +7,37 @@ export function parseArgs(argv) {
         const arg = argv[i];
         if (arg === "--project-root") {
             const value = argv[i + 1];
-            if (value === undefined) {
+            if (value === undefined || value.startsWith("--")) {
                 return { ...parsed, error: "argument --project-root: expected one argument" };
             }
             parsed.projectRoot = value;
             i += 1;
         }
         else if (arg?.startsWith("--project-root=")) {
-            parsed.projectRoot = arg.slice("--project-root=".length);
+            const value = arg.slice("--project-root=".length);
+            if (value.length === 0 || value.startsWith("--")) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+        }
+        else if (arg === "--session-id") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected one argument" };
+            }
+            const sessionId = value.trim();
+            if (sessionId.length === 0 || sessionId.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected a non-empty value" };
+            }
+            parsed.sessionId = sessionId;
+            i += 1;
+        }
+        else if (arg?.startsWith("--session-id=")) {
+            const sessionId = arg.slice("--session-id=".length).trim();
+            if (sessionId.length === 0 || sessionId.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected a non-empty value" };
+            }
+            parsed.sessionId = sessionId;
         }
         else {
             return { ...parsed, error: `unrecognized argument: ${arg}` };
@@ -29,6 +52,7 @@ export function run(argv) {
         return 2;
     }
     const result = releaseOccupancy(resolve(args.projectRoot), {
+        sessionId: args.sessionId,
         env: process.env,
     });
     const sink = result.code === 0 ? process.stdout : process.stderr;

package/dist/occupancy-steal.d.ts

@@ -3,6 +3,7 @@ export declare function parseArgs(argv: readonly string[]): {
     projectRoot: string;
     confirm: boolean;
     occupant: string | null;
+    sessionId?: string;
     error?: string;
 };
 export declare function run(argv: readonly string[]): number;

package/dist/occupancy-steal.js

@@ -10,25 +10,52 @@ export function parseArgs(argv) {
         }
         else if (arg === "--occupant") {
             const value = argv[i + 1];
-            if (value === undefined) {
+            if (value === undefined || value.startsWith("--")) {
                 return { ...parsed, error: "argument --occupant: expected one argument" };
             }
             parsed.occupant = value;
             i += 1;
         }
         else if (arg?.startsWith("--occupant=")) {
-            parsed.occupant = arg.slice("--occupant=".length);
+            const value = arg.slice("--occupant=".length);
+            if (value.length === 0 || value.startsWith("--")) {
+                return { ...parsed, error: "argument --occupant: expected one argument" };
+            }
+            parsed.occupant = value;
         }
         else if (arg === "--project-root") {
             const value = argv[i + 1];
-            if (value === undefined) {
+            if (value === undefined || value.startsWith("--")) {
                 return { ...parsed, error: "argument --project-root: expected one argument" };
             }
             parsed.projectRoot = value;
             i += 1;
         }
         else if (arg?.startsWith("--project-root=")) {
-            parsed.projectRoot = arg.slice("--project-root=".length);
+            const value = arg.slice("--project-root=".length);
+            if (value.length === 0 || value.startsWith("--")) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+        }
+        else if (arg === "--session-id") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected one argument" };
+            }
+            const sessionId = value.trim();
+            if (sessionId.length === 0 || sessionId.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected a non-empty value" };
+            }
+            parsed.sessionId = sessionId;
+            i += 1;
+        }
+        else if (arg?.startsWith("--session-id=")) {
+            const sessionId = arg.slice("--session-id=".length).trim();
+            if (sessionId.length === 0 || sessionId.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected a non-empty value" };
+            }
+            parsed.sessionId = sessionId;
         }
         else {
             return { ...parsed, error: `unrecognized argument: ${arg}` };
@@ -43,6 +70,7 @@ export function run(argv) {
         return 2;
     }
     const result = stealOccupancy(resolve(args.projectRoot), {
+        sessionId: args.sessionId,
         confirm: args.confirm,
         occupant: args.occupant ?? undefined,
         env: process.env,

package/dist/render-cli/prd-render-cli.js

@@ -1,13 +1,11 @@
 /**
  * Thin CLI wrapper for prd-render (mirrors ``scripts/prd_render.py``).
  *
- * Supports `--project-root <dir>` to resolve the spec artifact via the layout
- * resolver (#2132), preferring `xbrief/specification.xbrief.json` on migrated
- * trees and falling back to `vbrief/specification.vbrief.json` on legacy trees.
+ * Supports `--project-root <dir>` to resolve full-spec or greenfield authority
+ * through the shared authority resolver (#2132 / #3598).
  * When `--spec` is explicitly provided it takes precedence over `--project-root`.
  * Direct `--spec` / `--output` / `--force` flags are still accepted unchanged.
  */
-import { layout } from "@deftai/directive-core";
 import { parsePrdArgv, prdRenderMain } from "@deftai/directive-core/render";
 function parsePrdRenderCliArgv(argv) {
     const remaining = [];
@@ -30,12 +28,10 @@ function parsePrdRenderCliArgv(argv) {
 export function runPrdRenderCli(argv) {
     const { projectRoot, remaining } = parsePrdRenderCliArgv(argv);
     const parsedArgs = parsePrdArgv(remaining);
-    const spec = parsedArgs.spec !== undefined
-        ? parsedArgs.spec
-        : projectRoot !== undefined
-            ? layout.resolveSpecArtifactPath(projectRoot)
-            : undefined;
-    prdRenderMain({ ...parsedArgs, spec });
+    prdRenderMain({
+        ...parsedArgs,
+        projectRoot: parsedArgs.spec === undefined ? projectRoot : undefined,
+    });
     return 0;
 }
 //# sourceMappingURL=prd-render-cli.js.map

package/dist/session-ready.d.ts

@@ -4,6 +4,8 @@ export interface ParsedSessionReadyArgs {
     emitJson: boolean;
     withNetwork: boolean;
     repo: string | null;
+    /** #3611: explicit lifecycle owner injected by a host hook bridge. */
+    sessionId: string | null;
     error?: string;
 }
 /** Parse session:ready CLI args. */

package/dist/session-ready.js

@@ -15,6 +15,7 @@ export function parseArgs(argv) {
         emitJson: false,
         withNetwork: false,
         repo: null,
+        sessionId: null,
     };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -33,13 +34,13 @@ export function parseArgs(argv) {
         if (arg === "--help" || arg === "-h") {
             return {
                 ...parsed,
-                error: "usage: session:ready [--project-root <path>] [--repo OWNER/NAME] [--with-network] [--json]\n" +
+                error: "usage: session:ready [--project-root <path>] [--repo OWNER/NAME] [--session-id <id>] [--with-network] [--json]\n" +
                     "  One-shot recovery: session:start (if needed) + gated ritual + cache recovery (#2993).",
             };
         }
         if (arg === "--project-root") {
             const value = argv[i + 1];
-            if (value === undefined) {
+            if (value === undefined || value.startsWith("--")) {
                 return { ...parsed, error: "argument --project-root: expected one argument" };
             }
             parsed.projectRoot = value;
@@ -47,12 +48,37 @@ export function parseArgs(argv) {
             continue;
         }
         if (arg.startsWith("--project-root=")) {
-            parsed.projectRoot = arg.slice("--project-root=".length);
+            const value = arg.slice("--project-root=".length);
+            if (value.length === 0 || value.startsWith("--")) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+            continue;
+        }
+        if (arg === "--session-id") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected one argument" };
+            }
+            const sessionId = value.trim();
+            if (sessionId.length === 0 || sessionId.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected a non-empty value" };
+            }
+            parsed.sessionId = sessionId;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--session-id=")) {
+            const sessionId = arg.slice("--session-id=".length).trim();
+            if (sessionId.length === 0 || sessionId.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected a non-empty value" };
+            }
+            parsed.sessionId = sessionId;
             continue;
         }
         if (arg === "--repo") {
             const value = argv[i + 1];
-            if (value === undefined) {
+            if (value === undefined || value.startsWith("--")) {
                 return { ...parsed, error: "argument --repo: expected one argument" };
             }
             parsed.repo = value;
@@ -60,7 +86,11 @@ export function parseArgs(argv) {
             continue;
         }
         if (arg.startsWith("--repo=")) {
-            parsed.repo = arg.slice("--repo=".length);
+            const value = arg.slice("--repo=".length);
+            if (value.length === 0 || value.startsWith("--")) {
+                return { ...parsed, error: "argument --repo: expected one argument" };
+            }
+            parsed.repo = value;
             continue;
         }
         if (arg.startsWith("-")) {
@@ -80,6 +110,7 @@ export function run(argv = process.argv.slice(2)) {
     const projectRoot = resolve(args.projectRoot);
     const result = runSessionReady(projectRoot, {
         repo: args.repo,
+        sessionId: args.sessionId ?? undefined,
         sessionStartOptions: {
             allowOptionalNetwork: args.withNetwork ? true : undefined,
             writeHistory: false,
@@ -89,6 +120,7 @@ export function run(argv = process.argv.slice(2)) {
         process.stdout.write(`${JSON.stringify({
             ready: result.code === 0,
             exit_code: result.code,
+            session_id: result.sessionId,
             path: result.path,
             message: result.message,
             steps: result.steps,

package/dist/session-start.d.ts

@@ -36,6 +36,8 @@ export interface ParsedSessionStartArgs {
     steal: boolean;
     confirm: boolean;
     occupant: string | null;
+    /** #3611: explicit lifecycle owner injected by a host hook bridge. */
+    sessionId: string | null;
     error?: string;
 }
 /** Parse session:start CLI args, mirroring scripts/session_start.py. */

package/dist/session-start.js

@@ -34,6 +34,7 @@ export function parseArgs(argv) {
         steal: false,
         confirm: false,
         occupant: null,
+        sessionId: null,
     };
     const dialInputs = {};
     for (let i = 0; i < argv.length; i += 1) {
@@ -82,25 +83,33 @@ export function parseArgs(argv) {
         }
         else if (arg === "--project-root") {
             const value = argv[i + 1];
-            if (value === undefined) {
+            if (value === undefined || value.startsWith("--")) {
                 return { ...parsed, error: "argument --project-root: expected one argument" };
             }
             parsed.projectRoot = value;
             i += 1;
         }
         else if (arg?.startsWith("--project-root=")) {
-            parsed.projectRoot = arg.slice("--project-root=".length);
+            const value = arg.slice("--project-root=".length);
+            if (value.length === 0 || value.startsWith("--")) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
         }
         else if (arg === "--defer") {
             const value = argv[i + 1];
-            if (value === undefined) {
+            if (value === undefined || value.startsWith("--")) {
                 return { ...parsed, error: "argument --defer: expected one argument" };
             }
             parsed.deferValues.push(value);
             i += 1;
         }
         else if (arg?.startsWith("--defer=")) {
-            parsed.deferValues.push(arg.slice("--defer=".length));
+            const value = arg.slice("--defer=".length);
+            if (value.length === 0 || value.startsWith("--")) {
+                return { ...parsed, error: "argument --defer: expected one argument" };
+            }
+            parsed.deferValues.push(value);
         }
         else if (arg === "--task-size" || arg === "--ceremony-task-size") {
             const value = argv[i + 1];
@@ -282,16 +291,39 @@ export function parseArgs(argv) {
         else if (arg === "--confirm") {
             parsed.confirm = true;
         }
+        else if (arg === "--session-id") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected one argument" };
+            }
+            const sessionId = value.trim();
+            if (sessionId.length === 0 || sessionId.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected a non-empty value" };
+            }
+            parsed.sessionId = sessionId;
+            i += 1;
+        }
+        else if (arg?.startsWith("--session-id=")) {
+            const sessionId = arg.slice("--session-id=".length).trim();
+            if (sessionId.length === 0 || sessionId.startsWith("--")) {
+                return { ...parsed, error: "argument --session-id: expected a non-empty value" };
+            }
+            parsed.sessionId = sessionId;
+        }
         else if (arg === "--occupant") {
             const value = argv[i + 1];
-            if (value === undefined) {
+            if (value === undefined || value.startsWith("--")) {
                 return { ...parsed, error: "argument --occupant: expected one argument" };
             }
             parsed.occupant = value;
             i += 1;
         }
         else if (arg?.startsWith("--occupant=")) {
-            parsed.occupant = arg.slice("--occupant=".length);
+            const value = arg.slice("--occupant=".length);
+            if (value.length === 0 || value.startsWith("--")) {
+                return { ...parsed, error: "argument --occupant: expected one argument" };
+            }
+            parsed.occupant = value;
         }
         else {
             return { ...parsed, error: `unrecognized argument: ${arg}` };
@@ -358,6 +390,7 @@ export function run(argv) {
             steal: args.steal ? true : undefined,
             confirm: args.confirm ? true : undefined,
             occupant: args.occupant ?? undefined,
+            sessionId: args.sessionId ?? undefined,
             ...(args.ceremonyDepthOverride !== null
                 ? {
                     ceremonyDial: selectCeremonyDepth({

package/dist/toolchain-check.d.ts

@@ -2,6 +2,7 @@
 import { type CommandRunner } from "@deftai/directive-core/verify-env";
 export interface ToolchainCheckRunOptions {
     readonly runner?: CommandRunner;
+    readonly env?: NodeJS.ProcessEnv;
 }
 export declare function run(argv?: readonly string[], options?: ToolchainCheckRunOptions): number;
 //# sourceMappingURL=toolchain-check.d.ts.map

package/dist/toolchain-check.js

@@ -1,9 +1,48 @@
 #!/usr/bin/env node
 import { fileURLToPath } from "node:url";
 import { runToolchainCheck } from "@deftai/directive-core/verify-env";
+function parseArgs(argv) {
+    let consumer = false;
+    let projectRoot = process.cwd();
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? "";
+        if (arg === "--consumer") {
+            consumer = true;
+            continue;
+        }
+        if (arg === "--project-root") {
+            const value = argv[index + 1];
+            if (value === undefined || value.trim() === "" || value.startsWith("-")) {
+                return { consumer, projectRoot, error: "--project-root requires a path" };
+            }
+            projectRoot = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--project-root=")) {
+            const value = arg.slice("--project-root=".length);
+            if (value.trim() === "") {
+                return { consumer, projectRoot, error: "--project-root requires a path" };
+            }
+            projectRoot = value;
+            continue;
+        }
+        return { consumer, projectRoot, error: `unrecognized argument: ${arg}` };
+    }
+    return { consumer, projectRoot };
+}
 export function run(argv = process.argv.slice(2), options = {}) {
-    const consumer = argv.includes("--consumer");
-    const result = runToolchainCheck(options.runner, { consumer });
+    const parsed = parseArgs(argv);
+    if (parsed.error !== undefined) {
+        process.stderr.write(`toolchain-check: ${parsed.error}\n`);
+        process.stderr.write("Usage: deft toolchain-check [--consumer] [--project-root <path>]\n");
+        return 2;
+    }
+    const result = runToolchainCheck(options.runner, {
+        consumer: parsed.consumer,
+        projectRoot: parsed.projectRoot,
+        env: options.env ?? process.env,
+    });
     for (const line of result.lines) {
         process.stdout.write(`${line}\n`);
     }

package/dist/verify-pr-closeout-attestable.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    repo: string | null;
+    pr: number | null;
+    quiet: boolean;
+    error?: string;
+}
+/** Parse verify-pr-closeout-attestable CLI args. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Run the gate and return the process exit code. */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=verify-pr-closeout-attestable.d.ts.map

package/dist/verify-pr-closeout-attestable.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluate } from "@deftai/directive-core/pr-closeout-attestable";
+function parsePrNumber(raw) {
+    const trimmed = raw.startsWith("#") ? raw.slice(1) : raw;
+    if (!/^\d+$/.test(trimmed)) {
+        return null;
+    }
+    const value = Number(trimmed);
+    return Number.isInteger(value) && value > 0 ? value : null;
+}
+/** Parse verify-pr-closeout-attestable CLI args. */
+export function parseArgs(argv) {
+    const parsed = { projectRoot: ".", repo: null, pr: null, quiet: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--quiet") {
+            parsed.quiet = true;
+        }
+        else if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--repo") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --repo: expected one argument" };
+            }
+            parsed.repo = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--repo=")) {
+            parsed.repo = arg.slice("--repo=".length);
+        }
+        else if (arg === "--pr") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --pr: expected one argument" };
+            }
+            const pr = parsePrNumber(value);
+            if (pr === null) {
+                return { ...parsed, error: `argument --pr: expected a positive integer, got ${value}` };
+            }
+            parsed.pr = pr;
+            i += 1;
+        }
+        else if (arg?.startsWith("--pr=")) {
+            const value = arg.slice("--pr=".length);
+            const pr = parsePrNumber(value);
+            if (pr === null) {
+                return { ...parsed, error: `argument --pr: expected a positive integer, got ${value}` };
+            }
+            parsed.pr = pr;
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    if (parsed.pr === null) {
+        return { ...parsed, error: "argument --pr is required" };
+    }
+    return parsed;
+}
+/** Run the gate and return the process exit code. */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_pr_closeout_attestable: ${args.error}\n`);
+        return 2;
+    }
+    const result = evaluate(resolve(args.projectRoot), args.pr, {
+        repo: args.repo,
+        quiet: args.quiet,
+    });
+    if (result.message.length > 0) {
+        if (result.stream === "stdout") {
+            process.stdout.write(`${result.message}\n`);
+        }
+        else if (result.stream === "stderr") {
+            process.stderr.write(`${result.message}\n`);
+        }
+    }
+    return result.code;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-pr-closeout-attestable.js.map

package/dist/verify-subagent-alive.js

@@ -166,7 +166,11 @@ export function evaluateSubagentAliveGate(args, cwd = process.cwd()) {
     }
     lines.push("");
     lines.push("REDISPATCH_OK: host-reported running + missing/STALE heartbeat authorizes takeover.");
-    lines.push("Re-dispatch a replacement worker; do not wait on Cursor false-alive state.");
+    lines.push("A killed worker's delivery attempt stays running until cancelled.");
+    lines.push("Takeover: task swarm:pre-dispatch -- --scope-id <id> --target-id <worktree> --action cancel");
+    lines.push("then:     task swarm:pre-dispatch -- --scope-id <id> --target-id <worktree>");
+    lines.push("If verify:session-ritual --tier=gated fails, run session:start --rearm --session-id=<same> first.");
+    lines.push("Do not wait on Cursor false-alive state. Do not spawn while DENY_DUPLICATE_ACTIVE.");
     return {
         exitCode: EXIT_STALE,
         redispatchOk: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive",
-  "version": "0.107.0",
+  "version": "0.108.0",
   "description": "Directive CLI — npm install path for the Deft Directive framework.",
   "license": "MIT",
   "homepage": "https://deftai.github.io/directive/",
@@ -34,8 +34,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-core": "^0.107.0",
-    "@deftai/directive-content": "^0.107.0"
+    "@deftai/directive-core": "^0.108.0",
+    "@deftai/directive-content": "^0.108.0"
   },
   "scripts": {
     "build": "tsc -b"