jules-orchestrator-kit 0.74.0 → 0.75.0

package/src/self-audit.mjs

@@ -10,7 +10,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { gate } from "./engine.mjs";
 import { loadConfig, parseYaml } from "./config.mjs";
-import { matchesGlob } from "./security.mjs";
+import { matchesGlob, TAMPER_KIND_NAMES } from "./security.mjs";
 
 /** Convenience wrapper kept for the historical `matchGlob` name. */
 export function matchGlob(filepath, globPattern) {
@@ -85,6 +85,202 @@ export function auditWorktrees(opts = {}) {
   return { ok: true, worktreeDir, exists };
 }
 
+/**
+ * Parses the labels payload GitHub Actions exposes for a pull request.
+ * Accepts an array, raw `toJSON(...labels)` JSON string, or a plain comma-separated string.
+ *
+ * @param {string|Array} raw
+ * @returns {string[]}
+ */
+export function parseLabels(raw = "") {
+  if (Array.isArray(raw)) {
+    return raw.map((l) => (typeof l === "string" ? l : l && l.name) || "").filter(Boolean);
+  }
+  const text = String(raw || "").trim();
+  if (!text) return [];
+  try {
+    const parsed = JSON.parse(text);
+    if (Array.isArray(parsed)) {
+      return parsed.map((l) => (typeof l === "string" ? l : l && l.name) || "").filter(Boolean);
+    }
+  } catch (_) {}
+  return text.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * Resolves tamper guard waivers from PR labels bound to the exact head SHA.
+ *
+ * Test expectation waivers MUST be explicitly bound to the reviewed commit SHA
+ * (e.g. `allow-e:<40-hex-SHA>` or legacy `allow-test-expectation:<SHA>`).
+ * Short label `allow-e:<40-hex-SHA>` is 48 characters, fitting GitHub's 50-character limit.
+ * Unbound labels (without SHA) or stale labels (SHA mismatch) are rejected.
+ *
+ * @param {string|string[]} rawLabels - Array of labels, JSON string, or comma-separated string
+ * @param {string} headSha - Full 40-character commit SHA of the current PR head
+ * @returns {{ allowedKinds: string[], rejected: Array<{ label: string, reason: string }> }}
+ */
+export function resolveTestWaiverFromLabels(rawLabels = "", headSha = "") {
+  const labels = parseLabels(rawLabels);
+  const allowedKinds = new Set();
+  const rejected = [];
+  const normalizedHead = String(headSha || "").trim().toLowerCase();
+
+  for (const label of labels) {
+    const lower = label.trim().toLowerCase();
+
+    if (!lower.startsWith("allow-test-") && !lower.startsWith("allow-e:") && lower !== "allow-e") {
+      continue;
+    }
+
+    const parts = lower.split(":");
+    let kind = null;
+    let targetSha = null;
+
+    if (parts[0] === "allow-e") {
+      kind = "expectation";
+      if (parts.length > 1) {
+        targetSha = parts.slice(1).join(":");
+      }
+    } else if (parts[0] === "allow-test-expectation") {
+      kind = "expectation";
+      if (parts.length > 1) {
+        targetSha = parts.slice(1).join(":");
+      }
+    } else if (parts[0] === "allow-test-change" || parts[0] === "allow-test-changes") {
+      if (parts.length === 2) {
+        if (TAMPER_KIND_NAMES.includes(parts[1])) {
+          kind = parts[1];
+        } else {
+          kind = "expectation";
+          targetSha = parts[1];
+        }
+      } else if (parts.length >= 3) {
+        kind = parts[1];
+        targetSha = parts.slice(2).join(":");
+      } else {
+        kind = "expectation";
+      }
+    } else {
+      continue;
+    }
+
+    if (!targetSha) {
+      const canonicalFmt = parts[0] === "allow-e" || parts[0] === "allow-test-expectation"
+        ? "allow-e:<40-hex-SHA>"
+        : `${parts[0]}:<40-hex-SHA>`;
+      rejected.push({
+        label,
+        reason: `Unbound waiver: label has no commit SHA. Must be formatted as "${canonicalFmt}".`,
+      });
+      continue;
+    }
+
+    if (!/^[0-9a-f]{40}$/i.test(targetSha)) {
+      rejected.push({
+        label,
+        reason: `Invalid commit SHA "${targetSha}": must be exact 40 hexadecimal characters. Prefix matching is not permitted.`,
+      });
+      continue;
+    }
+
+    if (!normalizedHead || !/^[0-9a-f]{40}$/i.test(normalizedHead)) {
+      rejected.push({
+        label,
+        reason: `Cannot verify binding: HEAD_SHA "${headSha}" is missing or not a valid 40-character commit SHA.`,
+      });
+      continue;
+    }
+
+    if (targetSha.toLowerCase() !== normalizedHead) {
+      rejected.push({
+        label,
+        reason: `Stale waiver: label SHA "${targetSha}" does not match current HEAD SHA "${normalizedHead}".`,
+      });
+      continue;
+    }
+
+    if (TAMPER_KIND_NAMES.includes(kind)) {
+      allowedKinds.add(kind);
+    } else {
+      rejected.push({
+        label,
+        reason: `Unknown tamper kind "${kind}". Valid kinds: ${TAMPER_KIND_NAMES.join(", ")}`,
+      });
+    }
+  }
+
+  return {
+    allowedKinds: Array.from(allowedKinds),
+    rejected,
+  };
+}
+
+/**
+ * Resolves protected-path bypass waivers from PR labels bound to the exact head SHA.
+ *
+ * Protected path waivers MUST be explicitly bound to the reviewed commit SHA
+ * (e.g. `allow-p:<40-hex-SHA>` or legacy `allow-protected-paths:<40-hex-SHA>`).
+ * Short label `allow-p:<40-hex-SHA>` is 48 characters, fitting GitHub's 50-character limit.
+ * Unbound labels (without SHA), prefix matching, or stale labels (SHA mismatch) are rejected.
+ *
+ * @param {string|string[]} rawLabels - Array of labels, JSON string, or comma-separated string
+ * @param {string} headSha - Full 40-character commit SHA of the current PR head
+ * @returns {{ ok: boolean, boundSha?: string, rejected: Array<{ label: string, reason: string }> }}
+ */
+export function resolveProtectedWaiverFromLabels(rawLabels = "", headSha = "") {
+  const labels = parseLabels(rawLabels);
+  const normalizedHead = String(headSha || "").trim().toLowerCase();
+  const rejected = [];
+  let foundValid = false;
+
+  for (const label of labels) {
+    const lower = label.trim().toLowerCase();
+    if (!lower.startsWith("allow-protected-paths") && !lower.startsWith("allow-p:") && lower !== "allow-p") continue;
+
+    const parts = lower.split(":");
+    if (parts.length === 1) {
+      rejected.push({
+        label,
+        reason: 'Unbound waiver: label has no commit SHA. Must be formatted as "allow-p:<40-hex-SHA>".',
+      });
+      continue;
+    }
+
+    const targetSha = parts.slice(1).join(":");
+    if (!/^[0-9a-f]{40}$/i.test(targetSha)) {
+      rejected.push({
+        label,
+        reason: `Invalid commit SHA "${targetSha}": must be exact 40 hexadecimal characters. Prefix matching is not permitted.`,
+      });
+      continue;
+    }
+
+    if (!normalizedHead || !/^[0-9a-f]{40}$/i.test(normalizedHead)) {
+      rejected.push({
+        label,
+        reason: `Cannot verify binding: HEAD_SHA "${headSha}" is missing or not a valid 40-character commit SHA.`,
+      });
+      continue;
+    }
+
+    if (targetSha.toLowerCase() !== normalizedHead) {
+      rejected.push({
+        label,
+        reason: `Stale waiver: label SHA "${targetSha}" does not match current HEAD SHA "${normalizedHead}".`,
+      });
+      continue;
+    }
+
+    foundValid = true;
+  }
+
+  if (foundValid) {
+    return { ok: true, boundSha: normalizedHead, rejected };
+  }
+
+  return { ok: false, rejected };
+}
+
 /**
  * Audit gate rules (scope, payload governor, secret scanning, verification suite).
  */
@@ -93,13 +289,42 @@ export async function auditGates(opts = {}) {
   const config = opts.config || loadConfig(root);
   const base = opts.base || process.env.BASE_BRANCH || config.baseBranch || "main";
 
+  let allowProtected =
+    opts.allowProtected ??
+    (process.env.JULES_ALLOW_COMMAND_FILE_CHANGES === "true" ||
+      process.env.JULES_ALLOW_COMMAND_FILE_CHANGES === "1");
+
+  const rawLabels = opts.prLabels || process.env.PR_LABELS;
+  const headSha = opts.headSha || process.env.HEAD_SHA;
+
+  if (!allowProtected && rawLabels) {
+    const waiver = resolveProtectedWaiverFromLabels(rawLabels, headSha);
+    if (waiver.ok) {
+      allowProtected = true;
+    }
+    for (const rej of waiver.rejected || []) {
+      console.warn(`::warning::[scope-waiver] ${rej.label}: ${rej.reason}`);
+    }
+  }
+
+  let allowTestChanges = opts.allowTestChanges || process.env.JULES_ALLOW_TEST_CHANGES;
+  if (!allowTestChanges && rawLabels) {
+    const waiver = resolveTestWaiverFromLabels(rawLabels, headSha);
+    if (waiver.allowedKinds.length > 0) {
+      allowTestChanges = waiver.allowedKinds.join(",");
+    }
+    for (const rej of waiver.rejected) {
+      console.warn(`::warning::[tamper-waiver] ${rej.label}: ${rej.reason}`);
+    }
+  }
+
   return await gate({
     root,
     config,
     base,
     fix: process.env.ALLOW_AUTO_REPAIR === "true",
-    allowProtected: process.env.JULES_ALLOW_COMMAND_FILE_CHANGES === "true",
-    allowTestChanges: process.env.JULES_ALLOW_TEST_CHANGES || opts.allowTestChanges,
+    allowProtected,
+    allowTestChanges,
   });
 }
 
@@ -118,6 +343,15 @@ export async function runSelfAudit(opts = {}) {
   const gatesResult = await auditGates(optsWithContext);
 
   if (!gatesResult.ok) {
+    // The CLI's exit-6 banner intentionally does not print diff contents.
+    // Surface safe finding coordinates so a legitimate change can be repaired
+    // without disabling the independent audit or guessing at the failure.
+    if (gatesResult.code === 6) {
+      const findings = gatesResult.phases?.find((phase) => phase.phase === "secrets")?.findings || [];
+      for (const finding of findings) {
+        console.error(`Self-audit finding: ${finding.type || "UNKNOWN"} at ${finding.file || "unattributed"}${finding.line ? `:${finding.line}` : ""}`);
+      }
+    }
     return gatesResult;
   }
 

package/src/state.mjs

@@ -667,12 +667,17 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
   if (requested.size > 0) {
     for (const held of lockStatus(root)) {
       if (!held || held.taskId === taskId) continue;
-      if (!isLockLive(held)) continue;
 
       const overlap = (Array.isArray(held.files) ? held.files : [])
         .map((f) => normalizePath(f))
         .filter((f) => requested.has(f));
       if (overlap.length > 0) {
+        if (!isLockLive(held)) {
+          if (held.taskId) {
+            try { unlinkSync(join(lockDir, `${held.taskId}.json`)); } catch (_) {}
+          }
+          continue;
+        }
         return {
           ok: false,
           holder: held.agent,
@@ -723,6 +728,8 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
         const existing = JSON.parse(readFileSync(lockFile, "utf-8"));
         return { ok: false, holder: existing.agent, taskId };
       } catch (_) {
+        // Corrupted or 0-byte existing file: unlink so the task does not stay wedged.
+        try { unlinkSync(lockFile); } catch (_) {}
         return { ok: false, holder: "unknown", taskId };
       }
     }
@@ -754,8 +761,9 @@ export function releaseLock(taskId, rootOrOpts = resolveRoot()) {
   return false;
 }
 
-export function lockStatus(rootOrOpts = resolveRoot()) {
-  const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
+export function lockStatus(rootOrOpts = resolveRoot(), opts = {}) {
+  const root = typeof rootOrOpts === "string" ? rootOrOpts : (rootOrOpts?.root || resolveRoot());
+  const activeOnly = opts?.activeOnly === true;
   const lockDir = getLockDir(root);
   const locks = [];
   try {
@@ -764,7 +772,10 @@ export function lockStatus(rootOrOpts = resolveRoot()) {
       if (file.endsWith(".json")) {
         try {
           const content = readFileSync(join(lockDir, file), "utf-8");
-          locks.push(Object.freeze(JSON.parse(content)));
+          const record = JSON.parse(content);
+          const live = isLockLive(record);
+          if (activeOnly && !live) continue;
+          locks.push(Object.freeze({ ...record, live }));
         } catch (_) {}
       }
     }
@@ -788,6 +799,7 @@ export function isConcurrencyGroupLocked(groupName, rootOrOpts = resolveRoot(),
   const locks = lockStatus(rootOrOpts);
   for (const lock of locks) {
     if (excludeTaskId && lock.taskId === excludeTaskId) continue;
+    if (!isLockLive(lock)) continue;
     const lockGroup = String(lock.concurrencyGroup || lock.concurrency_group || "").trim().toLowerCase();
     if (lockGroup === targetGroup) {
       return true;
@@ -796,4 +808,88 @@ export function isConcurrencyGroupLocked(groupName, rootOrOpts = resolveRoot(),
   return false;
 }
 
+/**
+ * Scans .agent/state/locks/ for stale, expired, or corrupted lock records.
+ *
+ * Supported queue/process model:
+ * - Leased locks: reaped if Date.now() >= lockExpiry(record).
+ * - Process-bound locks: reaped if owner PID is dead (or recycled with different start time).
+ * - Corrupted files: 0-byte or unparseable JSON files reaped immediately.
+ * - Live locks: left completely untouched.
+ *
+ * @param {string|Object} [rootOrOpts=resolveRoot()]
+ * @param {Object} [opts]
+ * @param {boolean} [opts.dryRun=false] - When true, reports stale locks without deleting them.
+ * @returns {{ reapedCount: number, reaped: Array<{ file: string, taskId: string, agent: string, pid: number|null, reason: "corrupted"|"expired"|"dead-pid" }> }}
+ */
+export function reapStaleLocks(rootOrOpts = resolveRoot(), { dryRun = false } = {}) {
+  const root = typeof rootOrOpts === "string" ? rootOrOpts : (rootOrOpts?.root || resolveRoot());
+  const lockDir = getLockDir(root);
+
+  if (!existsSync(lockDir)) {
+    return { reapedCount: 0, reaped: [] };
+  }
+
+  const reaped = [];
+  let files = [];
+  try {
+    files = readdirSync(lockDir);
+  } catch (_) {
+    return { reapedCount: 0, reaped: [] };
+  }
+
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    const lockPath = join(lockDir, file);
+    let record = null;
+    let corrupted = false;
+
+    try {
+      const content = readFileSync(lockPath, "utf-8");
+      if (!content || !content.trim()) {
+        corrupted = true;
+      } else {
+        record = JSON.parse(content);
+      }
+    } catch (_) {
+      corrupted = true;
+    }
+
+    let shouldReap = false;
+    let reason = "";
+
+    if (corrupted) {
+      shouldReap = true;
+      reason = "corrupted";
+    } else if (!isLockLive(record)) {
+      shouldReap = true;
+      if (record.leased === true) {
+        reason = "expired";
+      } else if (record.expiresAt && Date.now() >= lockExpiry(record)) {
+        reason = "expired";
+      } else {
+        reason = "dead-pid";
+      }
+    }
+
+    if (shouldReap) {
+      if (!dryRun) {
+        try {
+          unlinkSync(lockPath);
+        } catch (_) {}
+      }
+      reaped.push({
+        file,
+        taskId: record?.taskId || file.replace(/\.json$/, ""),
+        agent: record?.agent || "unknown",
+        pid: record?.pid ?? null,
+        reason,
+      });
+    }
+  }
+
+  return { reapedCount: reaped.length, reaped };
+}
+
+
 

package/src/uninstall.mjs

@@ -0,0 +1,227 @@
+/**
+ * Undo a default `agentctl init`: remove kit-owned config and the runtime
+ * `.gitignore` block. Optional `--force` also removes legacy scaffold dirs.
+ *
+ * See docs/uninstall.md — this deliberately does not delete AGENTS.md,
+ * SPEC.md, or other paths that may contain project-owned content.
+ */
+
+import { existsSync, readFileSync, writeFileSync, rmSync, readdirSync, rmdirSync } from "node:fs";
+import { join } from "node:path";
+import {
+  RUNTIME_GITIGNORE_HEADER,
+  stripRuntimeGitignoreBlock,
+} from "./scaffold.mjs";
+
+/** Legacy scaffold directories owned by `init --force` / older 0.x releases. */
+export const FORCE_REMOVE_DIRS = [
+  ".agent/rules",
+  ".agent/prompts",
+  ".agent/workflows",
+  ".agent/jules-queue",
+];
+
+/**
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function looksLikeKitConfig(content) {
+  const text = String(content);
+  if (text.includes("Agent Orchestrator Kit Config")) return true;
+  // Minimal shape init writes: a versioned manifest with a provider key.
+  return /^version:\s*\d+/m.test(text) && /^provider:\s*\S+/m.test(text);
+}
+
+/**
+ * @param {string} root
+ * @returns {{ installed: boolean, hasConfig: boolean, hasGitignoreBlock: boolean, configPath: string|null }}
+ */
+export function detectKitInstallation(root) {
+  const configPath = join(root, ".agent", "config.yml");
+  let hasConfig = false;
+  if (existsSync(configPath)) {
+    try {
+      hasConfig = looksLikeKitConfig(readFileSync(configPath, "utf-8"));
+    } catch (_) {
+      hasConfig = false;
+    }
+  }
+
+  let hasGitignoreBlock = false;
+  const gitignorePath = join(root, ".gitignore");
+  if (existsSync(gitignorePath)) {
+    try {
+      hasGitignoreBlock = readFileSync(gitignorePath, "utf-8").includes(RUNTIME_GITIGNORE_HEADER);
+    } catch (_) {
+      hasGitignoreBlock = false;
+    }
+  }
+
+  return {
+    installed: hasConfig || hasGitignoreBlock,
+    hasConfig,
+    hasGitignoreBlock,
+    configPath: hasConfig ? ".agent/config.yml" : null,
+  };
+}
+
+/**
+ * @param {string} root
+ * @param {{ force?: boolean }} [options]
+ * @returns {{
+ *   ok: boolean,
+ *   installed: boolean,
+ *   willRemove: string[],
+ *   willCleanGitignore: boolean,
+ *   forceDirs: string[],
+ *   error?: string,
+ * }}
+ */
+export function planUninstall(root, options = {}) {
+  const force = Boolean(options.force);
+  const detection = detectKitInstallation(root);
+  if (!detection.installed) {
+    return {
+      ok: false,
+      installed: false,
+      willRemove: [],
+      willCleanGitignore: false,
+      forceDirs: [],
+      error: "No kit installation detected (missing .agent/config.yml and runtime gitignore block).",
+    };
+  }
+
+  const willRemove = [];
+  if (detection.hasConfig) willRemove.push(".agent/config.yml");
+
+  const forceDirs = [];
+  if (force) {
+    for (const rel of FORCE_REMOVE_DIRS) {
+      if (existsSync(join(root, rel))) forceDirs.push(rel);
+    }
+    willRemove.push(...forceDirs);
+  }
+
+  const willCleanGitignore = detection.hasGitignoreBlock;
+  if (willCleanGitignore) willRemove.push(".gitignore");
+
+  // `.agent/` itself is only removed when it would be empty after the planned
+  // deletions — reported so dry-run matches real execution.
+  const agentDir = join(root, ".agent");
+  if (existsSync(agentDir) && wouldAgentDirBeEmpty(root, {
+    removeConfig: detection.hasConfig,
+    forceDirs,
+  })) {
+    willRemove.push(".agent");
+  }
+
+  return {
+    ok: true,
+    installed: true,
+    willRemove: [...new Set(willRemove)],
+    willCleanGitignore,
+    forceDirs,
+  };
+}
+
+/**
+ * @param {string} root
+ * @param {{ removeConfig: boolean, forceDirs: string[] }} planned
+ */
+function wouldAgentDirBeEmpty(root, planned) {
+  const agentDir = join(root, ".agent");
+  if (!existsSync(agentDir)) return false;
+  let entries;
+  try {
+    entries = readdirSync(agentDir);
+  } catch (_) {
+    return false;
+  }
+  const removing = new Set();
+  if (planned.removeConfig) removing.add("config.yml");
+  for (const rel of planned.forceDirs) {
+    if (rel.startsWith(".agent/")) removing.add(rel.slice(".agent/".length).split("/")[0]);
+  }
+  return entries.every((name) => removing.has(name));
+}
+
+/**
+ * @param {string} root
+ * @param {{ force?: boolean, dryRun?: boolean }} [options]
+ * @returns {{
+ *   ok: boolean,
+ *   dryRun: boolean,
+ *   installed: boolean,
+ *   willRemove?: string[],
+ *   removed?: string[],
+ *   willCleanGitignore?: boolean,
+ *   cleanedGitignore?: boolean,
+ *   error?: string,
+ * }}
+ */
+export function uninstallKit(root, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const force = Boolean(options.force);
+  const plan = planUninstall(root, { force });
+  if (!plan.ok) {
+    return { ok: false, dryRun, installed: false, error: plan.error };
+  }
+
+  if (dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      installed: true,
+      willRemove: plan.willRemove,
+      willCleanGitignore: plan.willCleanGitignore,
+    };
+  }
+
+  const removed = [];
+
+  const configAbs = join(root, ".agent", "config.yml");
+  if (plan.willRemove.includes(".agent/config.yml") && existsSync(configAbs)) {
+    rmSync(configAbs, { force: true });
+    removed.push(".agent/config.yml");
+  }
+
+  for (const rel of plan.forceDirs) {
+    const abs = join(root, rel);
+    if (existsSync(abs)) {
+      rmSync(abs, { recursive: true, force: true });
+      removed.push(rel);
+    }
+  }
+
+  let cleanedGitignore = false;
+  const gitignorePath = join(root, ".gitignore");
+  if (plan.willCleanGitignore && existsSync(gitignorePath)) {
+    const current = readFileSync(gitignorePath, "utf-8");
+    const { text, stripped } = stripRuntimeGitignoreBlock(current);
+    if (stripped) {
+      writeFileSync(gitignorePath, text, "utf-8");
+      cleanedGitignore = true;
+      removed.push(".gitignore");
+    }
+  }
+
+  const agentDir = join(root, ".agent");
+  if (existsSync(agentDir)) {
+    try {
+      if (readdirSync(agentDir).length === 0) {
+        rmdirSync(agentDir);
+        removed.push(".agent");
+      }
+    } catch (_) {
+      // Leave the directory if it is not empty or not removable.
+    }
+  }
+
+  return {
+    ok: true,
+    dryRun: false,
+    installed: true,
+    removed: [...new Set(removed)],
+    cleanedGitignore,
+  };
+}

package/src/wizard-init.mjs

@@ -122,6 +122,17 @@ export function planInit(root = process.cwd(), options = {}) {
   // scaffolded limits always match what the runtime will later enforce.
   const tierPresetLimits = TIER_PROFILES[tierName] || TIER_PROFILES[FALLBACK_TIER];
 
+  // Same fail-closed rule as tier: an explicit `--profile` that is not one of
+  // PROFILE_NAMES must not silently become `standard`. Guessing wrong used to
+  // scaffold the everyday gate under a name the operator never chose.
+  if (options.profile && !PROFILE_NAMES.includes(String(options.profile).toLowerCase())) {
+    const rawProfile = String(options.profile).toLowerCase();
+    if (validTiers.includes(rawProfile)) {
+      throw new Error(`Invalid profile "${options.profile}". Valid profiles: ${PROFILE_NAMES.join(", ")}. Did you mean '--tier ${options.profile}'?`);
+    }
+    throw new Error(`Invalid profile "${options.profile}". Valid profiles: ${PROFILE_NAMES.join(", ")}.`);
+  }
+
   // Preserve existing config if present (ignored when pristine requested)
   let existingConfig = {};
   if (!options.pristine) {

package/src/wizard-task.mjs

@@ -476,7 +476,7 @@ export async function runTaskCreateWizard(root = process.cwd(), options = {}) {
   });
 
   // Perform Gate Preflight
-  const gateRes = await gate({ root, mode: "working-tree" });
+  const gateRes = await gate({ root, mode: "working-tree", allowProtected: Boolean(options.allowProtected) });
   if (!gateRes.ok && (gateRes.code === 3 || gateRes.code === 6) && !options.allowGateFailure) {
     const scopeViolations = gateRes.phases[0]?.violations || [];
     // A cold-start repository has nothing committed yet: every path init just
@@ -491,7 +491,13 @@ export async function runTaskCreateWizard(root = process.cwd(), options = {}) {
     const realViolations = scopeViolations.filter((v) => !v.file.startsWith(".agent/")) || [];
     const installArtifacts = new Set(untrackedOnboardingArtifacts(root, scopeViolations.map((v) => v.file)));
     const blockers = realViolations.filter((v) => !installArtifacts.has(v.file));
-    if (blockers.length > 0 || gateRes.code === 6) {
+    if (blockers.length > 0) {
+      const fileList = blockers.map((b) => b.file).join(", ");
+      throw new Error(
+        `Gate Preflight Rejected Task: Repository contains scope violations in protected/denied paths: ${fileList} (Exit 3).\n   To permit protected paths for this task, re-run with --allow-protected.`
+      );
+    }
+    if (gateRes.code === 6) {
       throw new Error(`Gate Preflight Rejected Task: Repository contains scope or secret violations (Exit ${gateRes.code}).`);
     }
   }