@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/planning-workspace.cjs

@@ -22,7 +22,7 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const activeWorkstreamStore = require("./active-workstream-store.cjs");
-const { createSharedPointerAdapter, createSessionScopedPointerAdapter, createMemoryPointerAdapter, getActiveWorkstream: getStoredActiveWorkstream, setActiveWorkstream: setStoredActiveWorkstream, clearActiveWorkstream: clearStoredActiveWorkstream, } = activeWorkstreamStore;
+const { createSharedPointerAdapter, createSessionScopedPointerAdapter, createMemoryPointerAdapter, getActiveWorkstream: getStoredActiveWorkstream, peekActiveWorkstream: peekStoredActiveWorkstream, setActiveWorkstream: setStoredActiveWorkstream, clearActiveWorkstream: clearStoredActiveWorkstream, diagnoseUnresolvedActiveWorkstream: diagnoseUnresolvedStoredActiveWorkstream, } = activeWorkstreamStore;
 // Track .planning/.lock files held by this process so they can be removed on exit.
 const _heldPlanningLocks = new Set();
 process.on('exit', () => {
@@ -120,6 +120,61 @@ function planningDir(cwd, ws, project) {
 function planningRoot(cwd) {
     return node_path_1.default.join(cwd, '.planning');
 }
+/**
+ * #3972: the ONE owner of "is this planning scope opted out of worktrees?" —
+ * the effective `workflow.use_worktrees === false` read every
+ * isolation-deciding surface must share (config-get's merged view is the
+ * contract). Ladder: the scoped config's OWN key wins (planningDir is
+ * project- and workstream-aware); otherwise the flat root's key, but only
+ * under the GSD_WORKSTREAM env gate — config-get deliberately does NOT
+ * inherit root under GSD_PROJECT alone, and this read must not diverge
+ * (#3963). Strict `=== false` (never coerced); any read failure degrades to
+ * "not opted out" (worktrees on — the fail-safe direction: the guard keeps
+ * enforcing). Direct file reads only — never loadConfig, which normalizes
+ * and rewrites config on paths that back sentinel writes.
+ */
+function worktreesOptedOut(cwd) {
+    // #3972 review: the WHOLE body is guarded — planningDir/planningRoot
+    // themselves throw on a GSD_PROJECT/GSD_WORKSTREAM value containing path
+    // separators or `..`, and this contract ("any failure degrades to not
+    // opted out — worktrees on, keep enforcing") must hold for that shape too.
+    try {
+        return worktreesOptedOutUnguarded(cwd);
+    }
+    catch {
+        return false;
+    }
+}
+function worktreesOptedOutUnguarded(cwd) {
+    const readCfg = (p) => {
+        try {
+            return JSON.parse(String(node_fs_1.default.readFileSync(p, 'utf8')));
+        }
+        catch {
+            return null;
+        }
+    };
+    const ownKey = (cfg) => {
+        if (cfg === null || typeof cfg !== 'object')
+            return { present: false, value: undefined };
+        const wf = cfg.workflow;
+        if (wf === null || typeof wf !== 'object' || Array.isArray(wf))
+            return { present: false, value: undefined };
+        const wfRec = wf;
+        return Object.prototype.hasOwnProperty.call(wfRec, 'use_worktrees')
+            ? { present: true, value: wfRec['use_worktrees'] }
+            : { present: false, value: undefined };
+    };
+    const scoped = ownKey(readCfg(node_path_1.default.join(planningDir(cwd), 'config.json')));
+    if (scoped.present)
+        return scoped.value === false;
+    if (process.env['GSD_WORKSTREAM']) {
+        const root = ownKey(readCfg(node_path_1.default.join(planningRoot(cwd), 'config.json')));
+        if (root.present)
+            return root.value === false;
+    }
+    return false;
+}
 // Sorted list of workstream directory names under `<root>/.planning/workstreams`,
 // or `[]` when the project is flat (no workstreams dir). Single source of truth
 // for the "workstream mode" detection shared by the #1912/#2028 fail-safe guards
@@ -136,6 +191,15 @@ function listAvailableWorkstreams(cwd) {
         return [];
     }
 }
+// #2142: the quick-task directory. Exported as its own function (not only as a
+// `planningPaths` key) because `audit.cts`'s `scanQuickTasks` receives an
+// already-resolved planning base rather than a `cwd`, so it cannot reach
+// `planningPaths`. Without this shared helper, adding the `quick` key would
+// leave TWO composers of `<planning>/quick` — the DEFECT.GENERATIVE-FIX shape
+// the `debug` key (#3149) was introduced to eliminate.
+function quickDirFrom(planningBase) {
+    return node_path_1.default.join(planningBase, 'quick');
+}
 function planningPaths(cwd, ws) {
     const base = planningDir(cwd, ws);
     return {
@@ -150,6 +214,8 @@ function planningPaths(cwd, ws) {
         // `debug_dir` field and `init.debug`'s — previously each composed its own
         // `path.join(planning, 'debug')` (DEFECT.GENERATIVE-FIX).
         debug: node_path_1.default.join(base, 'debug'),
+        // #2142: quick-task directory, composed via the shared quickDirFrom helper.
+        quick: quickDirFrom(base),
     };
 }
 /**
@@ -172,11 +238,15 @@ function withPlanningLock(cwd, fn, clock) {
     // on every call with no self-heal. Mirrors acquireStateLock's deadmanCeilingMs.
     const deadmanCeilingMs = 60000;
     const start = clock.now();
-    // Ensure .planning/ exists
-    try {
-        (0, shell_command_projection_cjs_1.platformEnsureDir)(planningDir(cwd));
-    }
-    catch { /* ok */ }
+    // Ensure .planning/ exists. A genuine failure here (EACCES/ENOSPC/EROFS/EMFILE)
+    // MUST surface immediately: the prior `catch { /* ok */ }` swallowed it, the lock
+    // write below then failed with ENOENT (parent dir missing), and ENOENT is retryable
+    // (PLANNING_LOCK_RETRY_ERRNOS — added for a Docker overlay-fs race), so the loop
+    // spun the full 10s budget and reported a PHANTOM "held by a live process"
+    // contention pointing at a nonexistent holder (epic #1879 / F16, #1884).
+    // `mkdirSync(recursive:true)` does not throw on an existing dir, so the normal
+    // path (dir already present) is unaffected; only real creation failures propagate.
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(planningDir(cwd));
     function acquireLock() {
         // Atomic create — fails if file exists
         node_fs_1.default.writeFileSync(lockPath, JSON.stringify({
@@ -345,9 +415,40 @@ function createPlanningWorkspace(cwd, opts = {}) {
 function getActiveWorkstream(cwd) {
     return getStoredActiveWorkstream(cwd);
 }
+// #3579 root-cause fix: read-only sibling of getActiveWorkstream, thin
+// pass-through to active-workstream-store's non-mutating peek. Callers that
+// only need to KNOW whether a workstream resolves (a guard's initial check,
+// a bootstrap that will re-derive the answer anyway) must use this instead
+// of getActiveWorkstream — the mutating variant self-heals (clears) a
+// present-but-unresolvable chain[0] value, and a later read in the SAME
+// process (another getActiveWorkstream call, or diagnoseUnresolvedActiveWorkstream)
+// would then observe already-cleared state instead of the original evidence,
+// silently changing the answer or losing the diagnostic reason. Self-heal
+// still happens — exactly once, wherever the real consuming call site invokes
+// getActiveWorkstream — this sibling just avoids triggering it prematurely.
+function peekActiveWorkstream(cwd) {
+    return peekStoredActiveWorkstream(cwd);
+}
 function setActiveWorkstream(cwd, name) {
     setStoredActiveWorkstream(cwd, name);
 }
+// #3579 item 1: read-only diagnostic sibling of getActiveWorkstream, thin
+// pass-through to active-workstream-store's chain walk. Lets the #1912/#2028
+// fail-safe guards (init.progress, phase.complete) distinguish "no marker at
+// all" from "a marker exists but didn't resolve" without duplicating the
+// resolution predicate.
+function diagnoseUnresolvedActiveWorkstream(cwd) {
+    return diagnoseUnresolvedStoredActiveWorkstream(cwd);
+}
+// #3579 item 1: human-readable clause for diagnoseUnresolvedActiveWorkstream's
+// `reason`, shared by the init.progress and phase.complete fail-safe guards so
+// the two error messages describe the same failure the same way instead of
+// drifting (CLAUDE.md's Generative Fix Divergence anti-pattern).
+function describeUnresolvedWorkstreamReason(reason) {
+    if (reason === 'invalid_name')
+        return 'the name is not a valid workstream name';
+    return "its workstream directory doesn't exist (it may have been renamed or removed)";
+}
 /**
  * Locate the CONTEXT.md file in a phase directory, handling both the bare
  * form (`CONTEXT.md`) and the padded-prefix convention (`NN-CONTEXT.md`,
@@ -385,6 +486,7 @@ function findContextMdIn(absDirOrFiles) {
     }
 }
 module.exports = {
+    worktreesOptedOut,
     createPlanningWorkspace,
     createSharedPointerAdapter,
     createSessionScopedPointerAdapter,
@@ -393,9 +495,13 @@ module.exports = {
     planningRoot,
     listAvailableWorkstreams,
     planningPaths,
+    quickDirFrom,
     withPlanningLock,
     getActiveWorkstream,
+    peekActiveWorkstream,
     setActiveWorkstream,
+    diagnoseUnresolvedActiveWorkstream,
+    describeUnresolvedWorkstreamReason,
     findContextMdIn,
     // Test seam (audit M1): inject a deterministic isPidAlive so the liveness-gated
     // steal decision is exercised without real pids. Mirrors capability-lock.cts.

package/gsd-core/bin/lib/probe-core.cjs

@@ -43,6 +43,9 @@ exports.projectTruths = projectTruths;
 exports.dispositionForUnverifiableTruth = dispositionForUnverifiableTruth;
 exports.runProbeCli = runProbeCli;
 const node_fs_1 = __importDefault(require("node:fs"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { ExitError } = cliExitModule;
 /** The LOCKED set of valid lifecycle statuses (the re-cut: no covered/backstop). */
 exports.VALID_STATUS = ['resolved', 'dismissed', 'unresolved'];
 function errMessage(e) {
@@ -372,7 +375,7 @@ function dispositionForProhibition(prohibition, context = {}) {
         };
     }
     // D4 GUARD: a judgment-tier (or unknown-tier) prohibition is NEVER a silent green from this
-    // deterministic helper — it always routes to human/LLM judgment review (ADR-550 D4; verify-phase.md).
+    // deterministic helper — it always routes to human/LLM judgment review (ADR-550 D4; gsd-verifier.md + references/verifier-phase-gates.md).
     // Only a test-tier item with wired enforcement evidence may go green; the producer that supplies
     // that evidence (`prohibition-enforcement`, #1259) runs the wired check and requires a genuine pass.
     if (tier === 'test') {
@@ -497,7 +500,7 @@ function runProbeCli(analyze, options) {
     const readFile = options.readFile ?? ((p) => node_fs_1.default.readFileSync(p, 'utf8'));
     const write = options.write ?? ((s) => { process.stdout.write(s); });
     const writeErr = options.writeErr ?? ((s) => { process.stderr.write(s); });
-    const exit = options.exit ?? ((code) => { process.exit(code); });
+    const exit = options.exit ?? ((code) => { throw new ExitError(code); });
     const reqPath = argv[2];
     const resPath = argv[3];
     if (!reqPath) {

package/gsd-core/bin/lib/profile-output.cjs

@@ -477,7 +477,7 @@ function generateSkillsSection(cwd) {
  */
 function extractSkillFrontmatter(content) {
     const result = { name: '', description: '' };
-    const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    const fmMatch = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
     if (!fmMatch)
         return result;
     const fmBlock = fmMatch[1];

package/gsd-core/bin/lib/profile-pipeline-command-router.cjs

@@ -13,12 +13,55 @@
  * Async note: cmdExtractMessages and cmdProfileSample are async functions.
  * dispatchCapabilityCommand (gsd-tools.cjs:366-371) explicitly errors if a
  * router returns a Promise. Therefore these router functions call the async
- * function WITHOUT await and WITHOUT returning the Promise. The async functions
- * end with output() or process.exit() so the process terminates correctly once
- * the event loop drains. Unhandled rejections are caught by the .catch() wrapper
- * to surface errors via the error() callback.
+ * function WITHOUT await and WITHOUT returning the Promise; the event loop
+ * drains once the returned promise settles. Since ADR-3889 (#3910), the
+ * pipeline functions terminate by THROWING ExitError (never process.exit()
+ * directly), so a rejection surfacing here can carry either a genuine error
+ * OR a declared ExitError termination — the `.catch()` below must
+ * distinguish them: an ExitError sets process.exitCode directly (mirroring
+ * cli-exit.cjs's own runMain, the only other place ExitError is caught),
+ * while any other rejection is surfaced via the `error()` callback exactly
+ * as before. Calling `error(exitErr.message)` for an ExitError would be
+ * wrong on two counts: it discards the real exit code (error() always
+ * terminates at 1) and it re-derives a message from ExitError's generic
+ * "process exit N" constructor default rather than the (already emitted, or
+ * intentionally absent) stderr output the throwing call site controls.
  */
-const { ERROR_REASON } = require('./io.cjs');
+const { ERROR_REASON, getJsonErrorMode } = require('./io.cjs');
+const { ExitError } = require('./cli-exit.cjs');
+
+/**
+ * Interpret a rejection from a fire-and-forget async pipeline call: an
+ * ExitError sets process.exitCode (and, for a non-zero code carrying a user
+ * message, writes it to stderr) exactly like runMain does; anything else
+ * reproduces io.cjs's error() stderr output byte-for-byte and sets
+ * process.exitCode directly instead of calling error() itself.
+ *
+ * error() (src/io.cts) is `never`-typed: it always throws ExitError(1) after
+ * writing to stderr. Calling it from inside this `.catch()` callback would
+ * throw from a detached promise chain that nothing awaits or re-catches —
+ * an unhandled promise rejection that Node (>=15, this repo's
+ * engines.node >= 24 default is --unhandled-rejections=throw) dumps as a
+ * raw stack trace on top of the clean line error() already wrote. Writing
+ * the same bytes directly and setting process.exitCode = 1 in place gets
+ * the identical observable stderr + exit code without ever throwing here.
+ */
+function _handlePipelineRejection(e, error) {
+  void error;
+  if (e instanceof ExitError) {
+    if (e.hasUserMessage && e.code !== 0) process.stderr.write(`${e.message}\n`);
+    process.exitCode = e.code;
+    return;
+  }
+  const message = e && e.message ? e.message : String(e);
+  if (getJsonErrorMode()) {
+    const payload = JSON.stringify({ ok: false, reason: ERROR_REASON.UNKNOWN, message }) + '\n';
+    process.stderr.write(payload);
+  } else {
+    process.stderr.write('Error: ' + message + '\n');
+  }
+  process.exitCode = 1;
+}
 
 // ─── Pipeline phase commands ───────────────────────────────────────────────────
 
@@ -51,7 +94,7 @@ function routeExtractMessages({ args, cwd, raw, error, _pipeline }) {
   // The function ends with output() or process.exit(); the event loop will drain.
   void cwd;
   p.cmdExtractMessages(projectArg, { sessionId, limit }, raw, sessionsPath)
-    .catch(e => { error(e && e.message ? e.message : String(e)); });
+    .catch(e => { _handlePipelineRejection(e, error); });
 }
 
 function routeProfileSample({ args, cwd, raw, error, _pipeline }) {
@@ -67,7 +110,7 @@ function routeProfileSample({ args, cwd, raw, error, _pipeline }) {
   const maxChars = maxCharsIdx !== -1 ? parseInt(args[maxCharsIdx + 1], 10) : 500;
   // cmdProfileSample is async — do NOT return the Promise.
   p.cmdProfileSample(sessionsPath, { limit, maxPerProject, maxChars }, raw)
-    .catch(e => { error(e && e.message ? e.message : String(e)); });
+    .catch(e => { _handlePipelineRejection(e, error); });
 }
 
 // ─── Output phase commands ─────────────────────────────────────────────────────

package/gsd-core/bin/lib/profile-pipeline.cjs

@@ -22,6 +22,9 @@ const node_readline_1 = __importDefault(require("node:readline"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioModule = require("./io.cjs");
 const { output, error, reapStaleTempFiles, ensureGsdTempDir, GSD_TEMP_DIR } = ioModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { ExitError } = cliExitModule;
 // ─── Session I/O Helpers ──────────────────────────────────────────────────────
 function getSessionsDir(overridePath) {
     const dir = overridePath || node_path_1.default.join(node_os_1.default.homedir(), '.claude', 'projects');
@@ -250,7 +253,7 @@ function cmdScanSessions(overridePath, options, raw) {
             }
         }
         process.stdout.write(`\nTotal: ${projects.length} projects\n`);
-        process.exit(0);
+        throw new ExitError(0);
     }
 }
 async function cmdExtractMessages(projectArg, options, raw, overridePath) {
@@ -376,11 +379,11 @@ async function cmdExtractMessages(projectArg, options, raw, overridePath) {
     };
     if (sessionsSkipped > 0 && sessionsProcessed > 0) {
         process.stdout.write(JSON.stringify(result, null, 2));
-        process.exit(2);
+        throw new ExitError(2);
     }
     else if (sessionsProcessed === 0 && sessionsSkipped > 0) {
         process.stdout.write(JSON.stringify(result, null, 2));
-        process.exit(1);
+        throw new ExitError(1);
     }
     else {
         output(result, raw, undefined);