@deftai/directive-core 0.105.0 → 0.107.0

package/dist/hooks/dispatcher.js

@@ -14,8 +14,9 @@ import { evaluateOccupancyWriteGate } from "../session/occupancy.js";
 import { emitSessionRitualBlockedProcessCost } from "../session/process-cost.js";
 import { markRitualStaleAfterCompact } from "../session/ritual-sentinel.js";
 import { runSessionStartHookWrite } from "../session/session-start-hook.js";
-import { formatRitualRecoveryInstruction, verifySessionRitual, } from "../session/verify-session-ritual.js";
+import { formatRitualRecoveryInstruction, verifySessionRitual, writeGateRitualOptions, } from "../session/verify-session-ritual.js";
 import { hookMcpArgsText, hookShellCommand, hookToolName, hookWriteTargetPath, missingToolNameMessage, record, } from "./classify/index.js";
+import { classifyProductDestForms, payloadWithInjectedWriteTarget } from "./dest-form.js";
 import { isAssistPosture, isEphemeralSpawn, isExploreSpawn, isReadOnlyHookContext, } from "./readonly.js";
 import { inspectActiveScope } from "./scope.js";
 import { isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool } from "./tools.js";
@@ -255,6 +256,17 @@ export function isHookHost(value) {
 export function isHookEvent(value) {
     return HOOK_EVENTS.includes(value);
 }
+function scopeNotReadyCoverageHint(toolName) {
+    if (isSpawnTool(toolName))
+        return "";
+    if (isShellTool(toolName)) {
+        return (" This deny is the active-scope write gate on a recognized Shell dest-form " +
+            "(git checkout --, git restore, rm/rmdir of in-repo paths).");
+    }
+    return (" This gate covers direct-write tools (Edit/Write) and implementation spawn, " +
+        "plus recognized Shell dest-forms (git checkout --, git restore, rm/rmdir). " +
+        "Other shell (python -c, cmd /c copy, git status) is not this deny.");
+}
 function deny(input, code, toolName, message, scopePath = null) {
     return {
         verdict: "deny",
@@ -578,15 +590,18 @@ function inspectMutationGates(input, toolName, seams, options) {
     try {
         // Mutation dispatch is a live gated boundary: active verification reruns
         // non-cacheable agent-hook readiness instead of trusting persisted success.
+        // Write-surface authority executes agent_hooks only (#3738). cache_fresh
+        // is not required and is never executed. doctor is read from the record.
         // Its allow fixture is non-write and its deny fixture is read-only, so the
         // installed-shim probe cannot recurse into this mutation path.
         ritual = (seams.verifyRitual ??
             seams.inspectRitual ??
-            ((root) => verifySessionRitual(root, {
-                tier: "gated",
-                posture: "mutation",
+            ((root) => verifySessionRitual(root, writeGateRitualOptions({
                 bypass: false,
-            })))(projectRoot);
+                runner: seams.ritualRunner,
+                detectWorkSelection: seams.detectWorkSelection,
+                runGit: seams.ritualRunGit,
+            }))))(projectRoot);
     }
     catch (cause) {
         // #2994: best-effort local process-cost; never changes deny verdict.
@@ -705,7 +720,8 @@ function inspectMutationGates(input, toolName, seams, options) {
                                 "assist posture (commands.md #1802) — do not fake `scope:activate` for notes.");
             }
             const denyCode = isSpawnTool(toolName) ? "spawn-not-ready" : "scope-not-ready";
-            return deny(input, denyCode, toolName, `Directive denied ${toolName}: ${scope.message}${proposedPathHint}`);
+            return deny(input, denyCode, toolName, `Directive denied ${toolName}: ${scope.message}${proposedPathHint}` +
+                scopeNotReadyCoverageHint(toolName));
         }
     }
     const allowCode = isSpawnTool(toolName) ? "spawn-ready" : "write-ready";
@@ -742,6 +758,58 @@ function inspectMutationGates(input, toolName, seams, options) {
         scopePath: scope.path,
     };
 }
+/**
+ * Route recognized Shell dest-forms through inspectMutationGates, then push/merge.
+ * Dest-form allow is kept when runtime authority has nothing classifiable.
+ */
+function decideShellDestFormsThenRuntimeAuthority(input, toolName, seams) {
+    const command = hookShellCommand(input.payload);
+    let destAllow = null;
+    let expansionDeny = null;
+    // #3438 / #3594: opt-in. `off` (the default) leaves Shell exactly as it was
+    // before this gate existed — unrecognized and fail-open — so landing the
+    // classifier cannot deny anything a consumer runs today. `enforce` turns on
+    // BOTH halves together: resolved dests through inspectMutationGates and
+    // fail-closed for targets that cannot be proved. ⊗ Do not split those two:
+    // enforcing only resolved dests would allow `cd x && rm y` while denying
+    // `rm x/y`, and enforcing only fail-closed would deny the compound while
+    // letting the in-scope simple form through unchecked.
+    // An unreadable policy resolves to `off`, which is the no-new-denials
+    // direction and matches the opt-in default rather than failing closed.
+    const destFormsEnforced = loadRuntimeAuthorityPolicySafe(input, seams)?.shellDestForms === "enforce";
+    if (command !== null && destFormsEnforced) {
+        for (const dest of classifyProductDestForms(command)) {
+            if (dest.expansion === true) {
+                expansionDeny = deny(input, "scope-not-ready", toolName, `Directive denied ${toolName}: Shell dest-form target is not reconstructable ` +
+                    "(compound command, glob/variable, leading ~, or a git context option). Name a " +
+                    "concrete path in ONE simple command — split `cd x && rm y` into a single " +
+                    "`rm x/y`, or one tool call per command — or use Edit/Write. Only a single simple " +
+                    "command with an absolute dest is checked soundly; a relative dest assumes the " +
+                    "shell is at the project root. Everything else stays fail-closed (#3438).");
+                continue;
+            }
+            const destInput = {
+                ...input,
+                payload: payloadWithInjectedWriteTarget(input.payload, dest.path),
+            };
+            const destDecision = inspectMutationGates(destInput, toolName, seams, {
+                proposedLifecycleExempt: true,
+            });
+            if (destDecision.verdict === "deny")
+                return destDecision;
+            destAllow = destDecision;
+        }
+    }
+    const runtime = decideShellOrMcpRuntimeAuthority(input, toolName, seams);
+    if (runtime.verdict === "deny")
+        return runtime;
+    if (expansionDeny !== null)
+        return expansionDeny;
+    if (destAllow !== null && runtime.code === "shell-op-unclassifiable") {
+        return destAllow;
+    }
+    return runtime;
+}
 /** Decide a normalized event using only the P0 direct-write policy. */
 export function decideHook(input, seams = {}) {
     const projectRoot = resolve(input.projectRoot);
@@ -930,13 +998,16 @@ export function decideHook(input, seams = {}) {
         }
         return inspectMutationGates(input, toolName, seams, { proposedLifecycleExempt: false });
     }
-    // Shell/Bash and classifiable MCP: enforce scopes.push / scopes.merge (#2711).
+    // Shell dest-forms (#3438): recognized product mutations share inspectMutationGates
+    // with Edit/Write (assist/scratch, proposed lifecycle, file_scope). Push/merge stay
+    // on runtimeAuthority (#2711). Non-dest unclassifiable shell (git status) fail-open.
+    if (isShellTool(toolName)) {
+        return decideShellDestFormsThenRuntimeAuthority(input, toolName, seams);
+    }
+    // Classifiable MCP: enforce scopes.push / scopes.merge (#2711).
     // Route bare push/merge MCP names (merge_pull_request, git_push, …) even when
     // isMcpTool is false — classifyMcpTool is the gate (dispatcher-side, no tools↔policy cycle).
-    // Does not require active-scope ritual — only runtimeAuthority when enabled.
-    if (isShellTool(toolName) ||
-        isMcpTool(toolName) ||
-        classifyMcpTool(toolName, hookMcpArgsText(input.payload)) !== null) {
+    if (isMcpTool(toolName) || classifyMcpTool(toolName, hookMcpArgsText(input.payload)) !== null) {
         return decideShellOrMcpRuntimeAuthority(input, toolName, seams);
     }
     if (!isDirectWriteTool(toolName)) {

package/dist/hooks/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./classify/index.js";
 export * from "./cursor-hooks.js";
+export * from "./dest-form.js";
 export * from "./dispatcher.js";
 export * from "./fixtures/index.js";
 export * from "./scope.js";

package/dist/hooks/index.js

@@ -1,5 +1,6 @@
 export * from "./classify/index.js";
 export * from "./cursor-hooks.js";
+export * from "./dest-form.js";
 export * from "./dispatcher.js";
 export * from "./fixtures/index.js";
 export * from "./scope.js";

package/dist/init-deposit/agent-hooks.d.ts

@@ -16,7 +16,7 @@ export declare const CURSOR_SESSION_HOOK_TIMEOUT_SECONDS = 5;
  * Mutation tool.before runs `inspectMutationGates` → gated
  * `verifySessionRitual`, which re-runs non-cacheable agent-hook readiness on
  * every boundary. Live readiness alone has a multi-host fixture ceiling of
- * ~12s (`content/contracts/agent-hook-readiness.md`); the historical deposit
+ * ~24s (`content/contracts/agent-hook-readiness.md`); the historical deposit
  * default of 5s was below that budget. Under Cursor `failClosed: true`, a
  * host timeout kill surfaces as opaque exit-1 with no Directive decision
  * code (#3246 / related #2864). Keep this above the readiness ceiling plus

package/dist/init-deposit/agent-hooks.js

@@ -24,7 +24,7 @@ export const CURSOR_SESSION_HOOK_TIMEOUT_SECONDS = 5;
  * Mutation tool.before runs `inspectMutationGates` → gated
  * `verifySessionRitual`, which re-runs non-cacheable agent-hook readiness on
  * every boundary. Live readiness alone has a multi-host fixture ceiling of
- * ~12s (`content/contracts/agent-hook-readiness.md`); the historical deposit
+ * ~24s (`content/contracts/agent-hook-readiness.md`); the historical deposit
  * default of 5s was below that budget. Under Cursor `failClosed: true`, a
  * host timeout kill surfaces as opaque exit-1 with no Directive decision
  * code (#3246 / related #2864). Keep this above the readiness ceiling plus

package/dist/intake/clause-derivation.d.ts

@@ -23,11 +23,15 @@ export interface ClauseStampPreparation {
     readonly ambiguity_attestation?: "none_found";
     readonly remediation?: string;
 }
+export declare const MISSING_AMBIGUITY_ATTESTATION_CAUSE: "missing_ambiguity_attestation";
+export declare const AMBIGUITY_ATTESTATION_REMEDIATION = "record ambiguity readings or attest none_found";
 export interface AmbiguityAttestationCheck {
     readonly ok: boolean;
     readonly attested: boolean;
     readonly kind: "ambiguous-clause" | "none_found" | "missing";
     readonly message: string;
+    readonly cause?: typeof MISSING_AMBIGUITY_ATTESTATION_CAUSE;
+    readonly remediation?: string;
 }
 /** True when activate/promote must run #3323 (absent, empty none_stated, or command-only). */
 export declare function needsClauseDerivation(acceptance: unknown): boolean;
@@ -45,6 +49,11 @@ export declare function countClauseProvenance(clauses: readonly TracedAcceptance
 export declare function prepareClauseStamp(clauses: readonly AcceptanceClause[], statement: string): ClauseStampPreparation;
 /** Config-error surface for verify:ac: attestation or an ambiguous clause with readings. */
 export declare function evaluateAmbiguityAttestation(acceptance: unknown): AmbiguityAttestationCheck;
+/**
+ * Fail-closed check for a *stamped* plan.acceptance (#3559).
+ * Command-only / empty floor blocks are not stamps; they keep the empty-resolution path.
+ */
+export declare function stampedAmbiguityAttestationError(acceptance: unknown): AmbiguityAttestationCheck | null;
 /**
  * Annotate stamped clauses with provenance and an ambiguity attestation.
  * An all-implementation stamp is stripped (never sufficient alone).

package/dist/intake/clause-derivation.js

@@ -9,6 +9,8 @@ import { ENV_RUN_SUMMARY_PATH, RunSummaryEmitter, } from "../run-summary/index.j
 import { deriveAcceptanceClauses, readAcceptanceClauses, serializeAcceptanceClauses, } from "../verify-ac/clauses.js";
 /** One-line remediation when a stamp has no statement-traceable clause (#3398). */
 export const CLAUSE_STAMP_IMPLEMENTATION_ONLY_REMEDIATION = "derive clauses from the statement's testable constraints";
+export const MISSING_AMBIGUITY_ATTESTATION_CAUSE = "missing_ambiguity_attestation";
+export const AMBIGUITY_ATTESTATION_REMEDIATION = "record ambiguity readings or attest none_found";
 const NARRATIVE_KEYS = [
     "Overview",
     "Description",
@@ -165,12 +167,22 @@ export function prepareClauseStamp(clauses, statement) {
         ambiguity_attestation: traced.some(hasAmbiguousReadings) ? undefined : "none_found",
     };
 }
-const AMBIGUITY_ATTESTATION_MISSING = "verify:ac config error: missing ambiguity attestation; record at least one ambiguous: true clause with readings, or set ambiguity_attestation: none_found";
+const AMBIGUITY_ATTESTATION_MISSING = `verify:ac config error: missing ambiguity attestation; ${AMBIGUITY_ATTESTATION_REMEDIATION}`;
+function missingAttestationCheck() {
+    return {
+        ok: false,
+        attested: false,
+        kind: "missing",
+        message: AMBIGUITY_ATTESTATION_MISSING,
+        cause: MISSING_AMBIGUITY_ATTESTATION_CAUSE,
+        remediation: AMBIGUITY_ATTESTATION_REMEDIATION,
+    };
+}
 /** Config-error surface for verify:ac: attestation or an ambiguous clause with readings. */
 export function evaluateAmbiguityAttestation(acceptance) {
     const rec = asRecord(acceptance);
     if (rec === null) {
-        return { ok: false, attested: false, kind: "missing", message: AMBIGUITY_ATTESTATION_MISSING };
+        return missingAttestationCheck();
     }
     const clauses = readAcceptanceClauses(rec);
     if (clauses.some(hasAmbiguousReadings)) {
@@ -179,7 +191,22 @@ export function evaluateAmbiguityAttestation(acceptance) {
     if (rec.ambiguity_attestation === "none_found") {
         return { ok: true, attested: true, kind: "none_found", message: "" };
     }
-    return { ok: false, attested: false, kind: "missing", message: AMBIGUITY_ATTESTATION_MISSING };
+    return missingAttestationCheck();
+}
+/**
+ * Fail-closed check for a *stamped* plan.acceptance (#3559).
+ * Command-only / empty floor blocks are not stamps; they keep the empty-resolution path.
+ */
+export function stampedAmbiguityAttestationError(acceptance) {
+    const rec = asRecord(acceptance);
+    if (rec === null) {
+        return null;
+    }
+    if (readAcceptanceClauses(rec).length === 0) {
+        return null;
+    }
+    const check = evaluateAmbiguityAttestation(rec);
+    return check.ok ? null : check;
 }
 function serializeTracedClauses(clauses) {
     return serializeAcceptanceClauses(clauses).map((row, index) => ({

package/dist/intake/github-auth-modes-cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { fileURLToPath } from "node:url";
-import { githubAuthModesMain } from "./github-auth-modes.js";
+import { githubAuthModesMain, INSTALLATION_IDENTITY_ISSUE_URL } from "./github-auth-modes.js";
 function parseArgs(argv) {
     const out = {};
     for (let i = 0; i < argv.length; i += 1) {
@@ -11,11 +11,23 @@ function parseArgs(argv) {
             out.repo = argv[++i];
         else if (arg === "--github-auth-mode")
             out.githubAuthMode = argv[++i];
+        else if (arg === "--expected-login")
+            out.expectedLogin = argv[++i];
+        else if (arg === "--expected-app-slug" || arg === "--expected-installation-id") {
+            throw new Error(`${arg} is not accepted; GitHub App installation identity is deferred to ${INSTALLATION_IDENTITY_ISSUE_URL}`);
+        }
     }
     return out;
 }
 export function mainEntry(argv = process.argv.slice(2)) {
-    return githubAuthModesMain(parseArgs(argv));
+    try {
+        return githubAuthModesMain(parseArgs(argv));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`${message}\n`);
+        return 2;
+    }
 }
 if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
     process.exit(mainEntry());

package/dist/intake/github-auth-modes.d.ts

@@ -3,12 +3,23 @@ import { probeRuntimeCapabilities, type RuntimeCapabilityReport } from "./platfo
 export declare const GITHUB_AUTH_MODE_INJECTED_TOKEN = "injected-token";
 export declare const GITHUB_AUTH_MODE_HOST_GH = "host-gh";
 export declare const KNOWN_GITHUB_AUTH_MODES: Set<string>;
-export declare const DEFAULT_VALIDATION_REPO = "deftai/directive";
+export declare const PRINCIPAL_KIND_USER = "user";
 export declare const FAILURE_MISSING_INJECTED_TOKEN = "missing_injected_token";
 export declare const FAILURE_GH_AUTH = "gh_auth_failed";
 export declare const FAILURE_API_UNREACHABLE = "api_unreachable";
 export declare const FAILURE_REPO_ACCESS = "repo_access_denied";
 export declare const FAILURE_INVALID_MODE = "invalid_auth_mode";
+export declare const FAILURE_MISSING_EXPECTED_PRINCIPAL = "missing_expected_principal";
+export declare const FAILURE_PRINCIPAL_MISMATCH = "principal_mismatch";
+export declare const FAILURE_MISSING_TARGET_REPO = "missing_target_repo";
+export declare const FAILURE_INSTALLATION_IDENTITY_UNVERIFIABLE = "installation_identity_unverifiable";
+export declare const ENV_EXPECTED_GITHUB_LOGIN = "DEFT_EXPECTED_GITHUB_LOGIN";
+export declare const INSTALLATION_IDENTITY_ISSUE_URL = "https://github.com/deftai/directive/issues/3693";
+/** GitHub-specific expected worker principal. Not a universal (provider-neutral) identity. */
+export type ExpectedGithubWorkerPrincipal = {
+    readonly kind: "user";
+    readonly login: string;
+};
 export interface GitHubAuthValidationResult {
     readonly ok: boolean;
     readonly githubAuthMode: string;
@@ -17,31 +28,63 @@ export interface GitHubAuthValidationResult {
     readonly detail: string;
     readonly remediation: string | null;
     readonly login: string | null;
+    readonly principal: ExpectedGithubWorkerPrincipal | null;
+    readonly validationRepo: string | null;
 }
 export type GhRunner = (args: readonly string[], environ: NodeJS.ProcessEnv) => CompletedProcess;
-export declare function findInjectedToken(environ: NodeJS.ProcessEnv): string | null;
-export declare function inferGithubAuthMode(runtimeReport: RuntimeCapabilityReport): string;
-export declare function validateInjectedTokenMode(environ: NodeJS.ProcessEnv, options?: {
+export type GitRemoteReader = (cwd?: string) => string | null;
+export interface GithubAuthValidationOptions {
     repo?: string;
     runtimeMode?: string | null;
     runGh?: GhRunner;
-}): GitHubAuthValidationResult;
-export declare function validateHostGhMode(environ: NodeJS.ProcessEnv, options?: {
+    expectedPrincipal?: ExpectedGithubWorkerPrincipal | null;
+    gitRemoteUrl?: string | null;
+    readGitRemote?: GitRemoteReader;
+    cwd?: string;
+}
+export declare function findInjectedToken(environ: NodeJS.ProcessEnv): string | null;
+export declare function inferGithubAuthMode(runtimeReport: RuntimeCapabilityReport): string;
+export declare function defaultReadGitOriginUrl(cwd?: string): string | null;
+export declare function parseOwnerRepoSlug(input: string): string | null;
+export declare function deriveValidationRepo(options: {
     repo?: string;
-    runtimeMode?: string | null;
-    runGh?: GhRunner;
-}): GitHubAuthValidationResult;
+    environ?: NodeJS.ProcessEnv;
+    gitRemoteUrl?: string | null;
+    readGitRemote?: GitRemoteReader;
+    cwd?: string;
+}): {
+    ok: true;
+    repo: string;
+} | {
+    ok: false;
+    detail: string;
+};
+export declare function resolveExpectedGithubWorkerPrincipal(environ: NodeJS.ProcessEnv, explicit?: ExpectedGithubWorkerPrincipal | null): ExpectedGithubWorkerPrincipal | {
+    error: string;
+} | null;
+export declare function isInstallationUserEndpointInapplicable(proc: CompletedProcess): boolean;
+export declare function formatUserApiFailureDetail(mode: string, proc: CompletedProcess): string;
+export declare function validateInjectedTokenMode(environ: NodeJS.ProcessEnv, options?: GithubAuthValidationOptions): GitHubAuthValidationResult;
+export declare function validateHostGhMode(environ: NodeJS.ProcessEnv, options?: GithubAuthValidationOptions): GitHubAuthValidationResult;
 export declare function validateGithubAuth(githubAuthMode: string, options?: {
     environ?: NodeJS.ProcessEnv;
     runtimeReport?: RuntimeCapabilityReport | null;
     repo?: string;
     runGh?: GhRunner;
+    expectedPrincipal?: ExpectedGithubWorkerPrincipal | null;
+    gitRemoteUrl?: string | null;
+    readGitRemote?: GitRemoteReader;
+    cwd?: string;
 }): GitHubAuthValidationResult;
 export declare function validateGithubAuthForWorker(githubAuthMode?: string | null, options?: {
     environ?: NodeJS.ProcessEnv;
     runtimeReport?: RuntimeCapabilityReport | null;
     repo?: string;
     runGh?: GhRunner;
+    expectedPrincipal?: ExpectedGithubWorkerPrincipal | null;
+    gitRemoteUrl?: string | null;
+    readGitRemote?: GitRemoteReader;
+    cwd?: string;
 }): GitHubAuthValidationResult;
 export declare function resultToDict(result: GitHubAuthValidationResult): Record<string, unknown>;
 export interface GitHubAuthModesCliArgs {
@@ -49,6 +92,8 @@ export interface GitHubAuthModesCliArgs {
     repo?: string;
     json?: boolean;
     runGh?: GhRunner;
+    expectedLogin?: string;
+    expectedPrincipal?: ExpectedGithubWorkerPrincipal | null;
 }
 export declare function githubAuthModesMain(args: GitHubAuthModesCliArgs): number;
 export { probeRuntimeCapabilities };