@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/active-workstream-store.cjs

@@ -22,6 +22,15 @@ const WORKSTREAM_SESSION_ENV_KEYS = [
     'GSD_SESSION_KEY',
     'CODEX_THREAD_ID',
     'CLAUDE_SESSION_ID',
+    // #3557 — Claude Code (≥ 2.1.132) exports its session id to Bash-tool
+    // subprocesses as CLAUDE_CODE_SESSION_ID. Without it the probe returned
+    // null on Claude Code, so every concurrent session in a working tree
+    // shared the single .planning/active-workstream pointer and cross-
+    // workstream STATE.md writes landed silently in the wrong file. Inserted
+    // beside the other runtime keys without reordering any existing entry;
+    // ahead of CLAUDE_CODE_SSE_PORT so the canonical id wins when both are
+    // present (runtime identity outranks terminal identity in this list).
+    'CLAUDE_CODE_SESSION_ID',
     'CLAUDE_CODE_SSE_PORT',
     'OPENCODE_SESSION_ID',
     'GEMINI_SESSION_ID',
@@ -76,6 +85,14 @@ function getControllingTtyToken() {
     return probeControllingTtyToken();
 }
 function getWorkstreamSessionKey() {
+    // #3883 (ADR-3473 §8.3): DECLARED DIFFERENT from generateSlugInternal
+    // (core-utils.cts), the canonical slug formula — deliberately, not a
+    // consolidation gap. The text slugified here is never caller-supplied: it
+    // is always one of the fixed ASCII WORKSTREAM_SESSION_ENV_KEYS identifier
+    // names above (e.g. "GSD_SESSION_KEY"), which already agree with the
+    // canonical's output byte-for-byte on this restricted input domain (no
+    // unicode, no length anywhere near the 60-char truncation boundary) — so
+    // delegating would add a require() edge for zero behavioral change.
     for (const envKey of WORKSTREAM_SESSION_ENV_KEYS) {
         const raw = process.env[envKey];
         const token = sanitizeWorkstreamSessionToken(raw);
@@ -183,21 +200,134 @@ function pickActiveWorkstreamAdapter(cwd, opts = {}) {
     }
     return createSharedPointerAdapter(cwd);
 }
-function getActiveWorkstream(cwd, opts = {}) {
-    const adapter = pickActiveWorkstreamAdapter(cwd, opts);
-    if (!adapter)
-        return null;
-    const name = adapter.read();
-    if (!name || !validateWorkstreamName(name)) {
-        adapter.clear();
-        return null;
+/**
+ * Read-resolution chain for getActiveWorkstream/peekActiveWorkstream (#3579).
+ *
+ * pickActiveWorkstreamAdapter (above) picks exactly one adapter and remains
+ * the seam for WRITE paths (set/clear), where "which pointer do I mutate" has
+ * only one right answer: the session pointer when a session key exists,
+ * otherwise the shared marker. Reads are different — a session that has
+ * never called `workstream use` has no opinion of its own, so it should
+ * inherit the repo-wide `.planning/active-workstream` marker rather than
+ * resolve to nothing. This returns an ORDERED chain: [owned, ...fallbacks].
+ * `chain[0]` ("owned") is exactly what pickActiveWorkstreamAdapter would have
+ * returned — resolveFromChain() self-heals only chain[0], never a fallback,
+ * so one session's read can never delete another scope's marker. Fallbacks
+ * are consulted ONLY when chain[0].read() comes back absent/empty; a session
+ * with its own (even stale/invalid) pointer never falls through — that is
+ * the isolation guarantee and it must not be weakened by inheritance.
+ */
+function pickActiveWorkstreamAdapterChain(cwd, opts = {}) {
+    if (opts.activeWorkstreamAdapter) {
+        return [opts.activeWorkstreamAdapter];
     }
-    const wsDir = node_path_1.default.join(planningRoot(cwd), 'workstreams', name);
-    if (!node_fs_1.default.existsSync(wsDir)) {
-        adapter.clear();
+    // #3579 item 3: when a caller supplies `opts.activeWorkstreamAdapters` at
+    // all, honor ONLY what it provides. The prior `|| createXPointerAdapter(...)`
+    // fallback synthesized a REAL filesystem adapter for whichever half a test
+    // double omitted — so a test injecting only `{ session }` silently touched
+    // the real shared marker file, and one injecting only `{ shared }` silently
+    // touched the real session-scoped tmp file. A missing half now gets a
+    // no-op in-memory adapter (always reads null) instead — this preserves the
+    // chain[0]-is-owned / rest-are-fallback shape resolveFromChain relies on
+    // without ever reaching disk. A caller that wants a real adapter for one
+    // half can still construct and pass it explicitly.
+    const injected = opts.activeWorkstreamAdapters;
+    const sessionKey = getWorkstreamSessionKey();
+    if (!sessionKey) {
+        const shared = injected
+            ? (injected.shared ?? createMemoryPointerAdapter(null))
+            : createSharedPointerAdapter(cwd);
+        return [shared];
+    }
+    const session = injected
+        ? (injected.session ?? createMemoryPointerAdapter(null))
+        : createSessionScopedPointerAdapter(cwd, sessionKey);
+    const shared = injected
+        ? (injected.shared ?? createMemoryPointerAdapter(null))
+        : createSharedPointerAdapter(cwd);
+    return session ? [session, shared] : [shared];
+}
+/**
+ * Shared "does this stored name resolve" predicate — format-valid AND its
+ * workstream directory exists. Factored out so resolveFromChain's owned/
+ * fallback arms (and diagnoseUnresolvedActiveWorkstream, #3579 item 1) share
+ * one definition of "resolvable" instead of re-deriving the same two checks.
+ */
+function resolvesToExistingWorkstream(cwd, name) {
+    if (!name || !validateWorkstreamName(name))
+        return false;
+    return node_fs_1.default.existsSync(node_path_1.default.join(planningRoot(cwd), 'workstreams', name));
+}
+/**
+ * Resolves a stored workstream name by walking an adapter chain.
+ *
+ * chain[0] is "owned" by this resolution: an absent/empty read falls through
+ * to the next adapter, but a present-and-bad read (invalid name, or a name
+ * whose workstream dir no longer exists) is resolved right there — self-
+ * healed via adapter.clear() when `selfHeal` is true, and never consulted
+ * further. Anything after chain[0] is a read-only fallback (the inherited
+ * marker): a bad value there resolves to null WITHOUT ever calling clear(),
+ * so a pointer-less session's read can never delete the shared marker that
+ * other sessions/scopes still depend on.
+ */
+function resolveFromChain(cwd, chain, selfHeal) {
+    if (chain.length === 0)
         return null;
+    const [owned, ...fallbacks] = chain;
+    const ownedName = owned.read();
+    if (ownedName) {
+        if (!resolvesToExistingWorkstream(cwd, ownedName)) {
+            if (selfHeal)
+                owned.clear();
+            return null;
+        }
+        return ownedName;
+    }
+    for (const adapter of fallbacks) {
+        const name = adapter.read();
+        if (resolvesToExistingWorkstream(cwd, name))
+            return name;
+    }
+    return null;
+}
+/**
+ * Diagnostic sibling of resolveFromChain (#3579 item 1). getActiveWorkstream/
+ * peekActiveWorkstream collapse EVERY unresolvable case to `null`, which is
+ * exactly right for routing — but a fail-safe guard reporting "no active
+ * workstream is set" to an operator needs to distinguish two very different
+ * situations that both produce that same `null`:
+ *
+ *   (a) no marker/pointer exists anywhere in the chain at all, vs.
+ *   (b) a marker/pointer EXISTS (names a value) but that value didn't
+ *       resolve — either the name fails validateWorkstreamName, or it's a
+ *       well-formed name whose `workstreams/<name>` directory is missing.
+ *
+ * Walks the same chain resolveFromChain uses and, for the first adapter that
+ * held a non-empty raw value, reports why it didn't resolve. Read-only: never
+ * calls adapter.clear() (mirrors peekActiveWorkstream, not getActiveWorkstream
+ * — a diagnostic read must not have side effects). Reuses
+ * resolvesToExistingWorkstream so this can never disagree with the actual
+ * resolution predicate above.
+ */
+function diagnoseUnresolvedActiveWorkstream(cwd, opts = {}) {
+    const chain = pickActiveWorkstreamAdapterChain(cwd, opts);
+    for (const adapter of chain) {
+        const raw = adapter.read();
+        if (!raw)
+            continue;
+        if (resolvesToExistingWorkstream(cwd, raw))
+            continue;
+        return {
+            present: true,
+            value: raw,
+            reason: validateWorkstreamName(raw) ? 'missing_workstream_dir' : 'invalid_name',
+        };
     }
-    return name;
+    return { present: false, value: null, reason: null };
+}
+function getActiveWorkstream(cwd, opts = {}) {
+    const chain = pickActiveWorkstreamAdapterChain(cwd, opts);
+    return resolveFromChain(cwd, chain, true);
 }
 /**
  * Read-only sibling of getActiveWorkstream (#2850): identical resolution —
@@ -212,16 +342,8 @@ function getActiveWorkstream(cwd, opts = {}) {
  * pointer file is left exactly as it was for whatever created it to fix.
  */
 function peekActiveWorkstream(cwd, opts = {}) {
-    const adapter = pickActiveWorkstreamAdapter(cwd, opts);
-    if (!adapter)
-        return null;
-    const name = adapter.read();
-    if (!name || !validateWorkstreamName(name))
-        return null;
-    const wsDir = node_path_1.default.join(planningRoot(cwd), 'workstreams', name);
-    if (!node_fs_1.default.existsSync(wsDir))
-        return null;
-    return name;
+    const chain = pickActiveWorkstreamAdapterChain(cwd, opts);
+    return resolveFromChain(cwd, chain, false);
 }
 function setActiveWorkstream(cwd, name, opts = {}) {
     const adapter = pickActiveWorkstreamAdapter(cwd, opts);
@@ -311,8 +433,10 @@ module.exports = {
     createSessionScopedPointerAdapter,
     createMemoryPointerAdapter,
     pickActiveWorkstreamAdapter,
+    pickActiveWorkstreamAdapterChain,
     getActiveWorkstream,
     peekActiveWorkstream,
+    diagnoseUnresolvedActiveWorkstream,
     setActiveWorkstream,
     clearActiveWorkstream,
     parseCliWorkstream,

package/gsd-core/bin/lib/adr-parser.cjs

@@ -14,6 +14,9 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const security_cjs_1 = require("./security.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { ExitError, runMain } = cliExitModule;
 const STATUS_REJECT_SET = new Set(['superseded', 'rejected', 'deprecated']);
 const CANONICAL_HEADERS = {
     status: ['status', 'state', 'lifecycle', 'stage'],
@@ -405,13 +408,16 @@ function main(argv) {
     process.stdout.write(JSON.stringify(parsed, null, 2));
 }
 if (require.main === module) {
-    try {
-        main(process.argv.slice(2));
-    }
-    catch (error) {
-        process.stderr.write(`Error: ${error.message}\n`);
-        process.exit(1);
-    }
+    runMain(() => {
+        try {
+            main(process.argv.slice(2));
+        }
+        catch (err) {
+            // ExitError with a message so runMain's catch writes it verbatim
+            // (byte-identical to the prior `Error: ${message}\n` process.exit(1)).
+            throw new ExitError(1, `Error: ${err.message}`);
+        }
+    });
 }
 module.exports = {
     CANONICAL_HEADERS,