fix(#3579): a pointer-less session inherits the repo active-workstream marker (#3616)

* test(3579): failing-first coverage for repo-marker inheritance A session that carries an identity but has never run 'workstream use' reads an absent session pointer, resolves null, and composes the flat .planning tree even when .planning/active-workstream names a live workstream. These tests fail on that and pin the invariants the fix must not break: a session with its own pointer is never repointed, and a session that merely lacked a pointer must never clear the shared marker on another session's behalf. * fix(3579): a pointer-less session inherits the repo active-workstream marker RED proven at 157cae26: the three inheritance tests failed while every isolation and negative control passed on base — the gap, and nothing else. pickActiveWorkstreamAdapter returned exactly ONE adapter: the session-scoped one whenever a session key existed, so the shared .planning/active-workstream marker was never consulted. getWorkstreamSessionKey resolves a key from ~13 env vars or the controlling TTY, so on any normal interactive terminal a key almost always exists — which is why a session that had never run 'workstream use' read an absent pointer, resolved null, and composed the FLAT planning tree even though the repo marker named a live workstream. Reads misreported; writes corrupted the superseded flat STATE. Silent, because the stale tree is well-formed. This was a genuine design fork, not an oversight: references/workstream-flag.md documented step 4 as a fallback 'when no session key exists', and the session isolation that buys is deliberate (#2850). The issue's Agent Brief left the choice open and said the reference doc should match whatever semantics ship. The maintainer ruled in chat for inheritance. Resolution now walks an ORDERED chain — session adapter first, shared second — and only a null from the session adapter falls through to the marker. Strictly additive: it can only turn a null into a name, never change a name that already resolves. The dangerous part is clear() ownership. resolveFromChain treats chain[0] as owned: only it is ever cleared, and only under selfHeal (getActiveWorkstream, never peek). An INHERITED marker is read-only — a stale value there resolves null and the file is left alone. Without that, one pointer-less session's read would delete the repo marker for every other session, which is a worse bug than the one being fixed. Covered by a test that asserts the marker still exists on disk after such a read. peekActiveWorkstream inherits but still mutates nothing (#2850 — the statusline draws on every render). references/workstream-flag.md's Resolution Priority is rewritten to match, keeping the session-isolation rationale and noting that inheritance does not weaken it: a session that owns a pointer is never repointed. Fixes #3579 * fix(3579): correct the guard diagnostics and lock the clear-semantics Three review passes; every finding fixed inline. MISSING ACCEPTANCE CRITERION (spec pass). The brief requires refusal diagnostics that distinguish 'marker present but the session lookup missed it' from 'no workstream set at all', and the two workstream-mode fail-safe guards were byte-for-byte untouched — still emitting a generic 'no active workstream is set' even when a marker exists and merely names a missing directory. Both guards (cmdPhaseComplete, cmdInitProgress) now branch on a new read-only diagnoseUnresolvedActiveWorkstream, which reuses the SAME resolvesToExistingWorkstream predicate resolveFromChain uses, so the diagnosis and the resolution cannot disagree. Two typed reasons added to ERROR_REASON; both arms still refuse — the fail-closed behavior is unchanged, only the message is now true. REAL TEST FAILURE, not a flake. The remote run failed 'clearing one session does not clear another session pointer'. That describe uses before() rather than beforeEach, so one tmpDir is shared and an earlier test writes active-workstream=beta into it; under inheritance the just-cleared session picks that marker up and resolves beta instead of null. The failure is a CORRECT consequence of Option A surfaced through an order-dependent fixture. The test now establishes its own marker state explicitly — its real intent (clearing A must not disturb B's pointer) is preserved and not weakened — and a new test pins the semantic deliberately: clearing a session pointer returns that session to INHERITING the marker, it does not force flat mode. Documented in references/workstream-flag.md, including how to actually get flat behavior. Also from review: partial activeWorkstreamAdapters injection no longer silently synthesizes a REAL filesystem adapter for the missing half (a latent test-isolation trap); the duplicated validate-then-existsSync logic is factored into one predicate; and the two try/finally test bodies are converted to t.after per CONTRIBUTING. New coverage: whitespace/empty shared marker; a session whose OWN pointer is stale while the marker names a different valid workstream (must self-heal to null, never inherit — the isolation guarantee at its sharpest); and both new diagnostic arms asserted on structured --json-errors output rather than prose. * fix(3579): read resolvability with the non-mutating peek, not the self-healing resolver Three of our own new tests failed on 7f5e706a. All three had ONE root cause, and none was fixed by relaxing an assertion. gsd-tools.cjs's bootstrap called the MUTATING getActiveWorkstream unconditionally on every invocation, purely to populate routing env. On an unresolvable pointer that self-healed — cleared it — BEFORE the dispatched command ran its own resolution. A second read in the same process then observed already-cleared state: - Isolation violation: a session whose own pointer was stale had it cleared by the bootstrap, so cmdWorkstreamGet's own resolution found a pointer-LESS session and inherited the shared marker ('beta' instead of null). Exactly the guarantee #2850 exists to protect, defeated across two calls rather than within one. - Guard diagnostics: the guards' own truthiness check also used the mutating resolver, so it cleared the invalid marker and the immediately-following read-only diagnosis found nothing and reported none_active instead of marker_unresolved. So a single invocation's answer depended on how many times it resolved. The bootstrap self-heal is PRE-EXISTING and was harmless while pointer-less meant flat — inheritance is what made it answer-changing, so this fix belongs here. Every call site that only CHECKS resolvability — the bootstrap, both fail-safe guards' truthiness check, and two informational init report fields — now uses the non-mutating peekActiveWorkstream. Self-heal is unchanged in active-workstream-store and still fires exactly once, at whichever site actually consumes the workstream. Verified by driving the real CLI against temp fixtures, since the suite cannot run locally: stale-own-pointer resolves null with the marker intact; both guard arms report marker_unresolved with missing_workstream_dir / invalid_name and the marker survives; no-marker still reports none_active; identity-less self-heal still deletes an invalid marker byte-identically to pre-#3579; and a session with a valid own pointer still wins. * chore(3579): backfill changeset PR number (#3616) * test(3579): kill the surviving mutants in the new resolution code CI's Stryker gate failed: active-workstream-store scored 79.45% against a break threshold of 80 — 259 killed, 67 survived, at 'Ran 1.00 tests per mutant on average'. The survivors cluster in the code this PR added (pickActiveWorkstreamAdapterChain, resolvesToExistingWorkstream, resolveFromChain, diagnoseUnresolvedActiveWorkstream): the CLI-level tests exercise those paths but do not DISCRIMINATE their branches, which is precisely what a surviving mutant means. Raised by strengthening assertions, never by touching the threshold. 21 unit tests added to the existing unit suite, each written to fail under a specific named mutant, using the module's injected adapter seams and createMemoryPointerAdapter so they stay hermetic under Stryker's per-mutant reruns: - chain shape with and without a session key, asserting length AND element identity (kills the if(false), the ': []' array mutant, and the block removal) - partial adapter injection, asserting the missing half is an inert memory adapter that never touches the filesystem (kills the three '??' -> '&&' mutants) - both arms of '!name || !validateWorkstreamName(name)' as SEPARATE tests — an absent name and a non-empty invalid one — which is what kills the '||' -> '&&' mutant - self-heal discrimination: getActiveWorkstream must clear an unresolvable owned pointer and peekActiveWorkstream must not, asserted on adapter state after each (kills if(selfHeal) -> if(true)) - fallback arm both ways: a fallback that resolves and one that does not - diagnoseUnresolvedActiveWorkstream asserted as a full object per case, with the reason strings compared exactly (kills present:true -> false and both StringLiteral mutants) One mutant is deliberately left: 'if (chain.length === 0)' -> 'if (false)'. The branch is structurally unreachable — the only chain source always returns a 1- or 2-element array literal — and resolveFromChain is not exported. Killing it would mean exporting an internal or deleting a defensive guard; neither is worth doing for a mutant, and the score clears 80 without it. Recorded here rather than left unexplained. Every new assertion was evaluated against the built module with real fixtures before committing, since the suite cannot run locally. --------- Co-authored-by: sim <sim@local>
2026-08-18 11:37:44 -04:00
parent 682eaae3f0
commit 9de4d67118
10 changed files with 780 additions and 46 deletions
--- a/tests/workstream.test.cjs
+++ b/tests/workstream.test.cjs
@@ -167,6 +167,17 @@ describe('session-scoped active workstream routing', () => {
  });

  test('clearing one session does not clear another session pointer', () => {
+    // A prior test in this shared-tmpDir block ('session-scoped pointer ignores
+    // legacy shared active-workstream file') writes 'beta' into the shared
+    // .planning/active-workstream marker. Under #3579 semantics, a cleared
+    // session INHERITS that marker instead of resolving flat — so leaving the
+    // marker in place here would make this test assert marker-inheritance
+    // behavior it never intended to cover (that is pinned separately below).
+    // This test's real intent is sibling-pointer isolation, not inheritance,
+    // so remove the marker to make alpha's post-clear resolution independent
+    // of whatever an earlier test in this block left on disk.
+    try { fs.unlinkSync(path.join(tmpDir, '.planning', 'active-workstream')); } catch {}
+
    const clearAlpha = runGsdTools(['workstream', 'set', '--clear', '--raw'], tmpDir, { GSD_SESSION_KEY: 'session-alpha' });
    const alpha = runGsdTools(['workstream', 'get'], tmpDir, { GSD_SESSION_KEY: 'session-alpha' });
    const beta = runGsdTools(['workstream', 'get', '--raw'], tmpDir, { GSD_SESSION_KEY: 'session-beta' });
@@ -242,6 +253,220 @@ describe('session resolution hardening', () => {
  });
 });

+// #3579: a session that has an identity (session key) but has never run
+// `workstream use` must inherit the repo-wide `.planning/active-workstream`
+// marker instead of resolving to nothing. peekActiveWorkstream has no CLI
+// surface (only the statusline hook calls it), so these tests require the
+// built module directly — same pattern as the planning-workspace.cjs require
+// used elsewhere in this file.
+describe('session inherits shared marker when pointer-less (#3579)', () => {
+  let tmpDir;
+  const {
+    getActiveWorkstream,
+    peekActiveWorkstream,
+  } = require('../gsd-core/bin/lib/active-workstream-store.cjs');
+
+  beforeEach(() => {
+    tmpDir = createFixture();
+
+    for (const [ws, status] of [['alpha', 'Alpha active'], ['beta', 'Beta active']]) {
+      const wsDir = path.join(tmpDir, '.planning', 'workstreams', ws);
+      fs.mkdirSync(path.join(wsDir, 'phases'), { recursive: true });
+      fs.writeFileSync(path.join(wsDir, 'STATE.md'), `# State\n**Status:** ${status}\n`);
+    }
+  });
+
+  afterEach(() => cleanup(tmpDir));
+
+  test('session key present, no session pointer, marker names an existing workstream -> inherits the marker', () => {
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'active-workstream'), 'alpha\n');
+
+    const result = runGsdTools(['workstream', 'get', '--raw'], tmpDir, { GSD_SESSION_KEY: 'no-pointer-session' });
+
+    assert.ok(result.success, `get failed: ${result.error}`);
+    assert.strictEqual(result.output, 'alpha');
+  });
+
+  test('peekActiveWorkstream inherits the marker and mutates nothing', (t) => {
+    const markerPath = path.join(tmpDir, '.planning', 'active-workstream');
+    fs.writeFileSync(markerPath, 'alpha\n');
+    const sessionDir = getSessionPointerDir(tmpDir);
+    const savedSessionKey = process.env.GSD_SESSION_KEY;
+    process.env.GSD_SESSION_KEY = 'peek-no-pointer';
+    t.after(() => {
+      if (savedSessionKey !== undefined) process.env.GSD_SESSION_KEY = savedSessionKey;
+      else delete process.env.GSD_SESSION_KEY;
+    });
+
+    const resolved = peekActiveWorkstream(tmpDir);
+    assert.strictEqual(resolved, 'alpha');
+    assert.strictEqual(fs.readFileSync(markerPath, 'utf-8'), 'alpha\n', 'peek must not mutate the shared marker');
+    assert.ok(!fs.existsSync(sessionDir), 'peek must not create a session pointer file');
+  });
+
+  test('session pointer names beta while marker names alpha -> resolves beta, marker untouched (isolation)', () => {
+    const markerPath = path.join(tmpDir, '.planning', 'active-workstream');
+    fs.writeFileSync(markerPath, 'alpha\n');
+    runGsdTools(['workstream', 'set', 'beta', '--raw'], tmpDir, { GSD_SESSION_KEY: 'has-own-pointer' });
+
+    const result = runGsdTools(['workstream', 'get', '--raw'], tmpDir, { GSD_SESSION_KEY: 'has-own-pointer' });
+
+    assert.ok(result.success, `get failed: ${result.error}`);
+    assert.strictEqual(result.output, 'beta');
+    assert.strictEqual(fs.readFileSync(markerPath, 'utf-8'), 'alpha\n', 'session with its own pointer must never repoint the shared marker');
+  });
+
+  test('workstream set --clear with a valid repo marker present -> session returns to inheriting the marker, not flat', () => {
+    const markerPath = path.join(tmpDir, '.planning', 'active-workstream');
+    fs.writeFileSync(markerPath, 'alpha\n');
+    runGsdTools(['workstream', 'set', 'beta', '--raw'], tmpDir, { GSD_SESSION_KEY: 'clear-then-inherit-session' });
+
+    const clear = runGsdTools(['workstream', 'set', '--clear', '--raw'], tmpDir, { GSD_SESSION_KEY: 'clear-then-inherit-session' });
+    const result = runGsdTools(['workstream', 'get', '--raw'], tmpDir, { GSD_SESSION_KEY: 'clear-then-inherit-session' });
+
+    assert.ok(clear.success, `clear failed: ${clear.error}`);
+    assert.ok(result.success, `get after clear failed: ${result.error}`);
+    assert.strictEqual(
+      result.output,
+      'alpha',
+      'clearing a session pointer must fall back to inheriting the shared marker (step 4), not resolve to null/flat',
+    );
+  });
+
+  test('no session key, marker present -> resolves the marker (pre-existing path stays green)', () => {
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'active-workstream'), 'alpha\n');
+
+    const result = runGsdTools(['workstream', 'get', '--raw'], tmpDir, {});
+
+    assert.ok(result.success, `get failed: ${result.error}`);
+    assert.strictEqual(result.output, 'alpha');
+  });
+
+  test('no workstreams/ dir -> flat/null, unchanged', (t) => {
+    // createFixture() only creates .planning/phases, not .planning/workstreams.
+    const flatDir = createFixture();
+    t.after(() => cleanup(flatDir));
+
+    const savedSessionKey = process.env.GSD_SESSION_KEY;
+    process.env.GSD_SESSION_KEY = 'flat-no-workstreams-dir';
+    t.after(() => {
+      if (savedSessionKey !== undefined) process.env.GSD_SESSION_KEY = savedSessionKey;
+      else delete process.env.GSD_SESSION_KEY;
+    });
+
+    assert.strictEqual(getActiveWorkstream(flatDir), null);
+    assert.strictEqual(peekActiveWorkstream(flatDir), null);
+  });
+
+  test('marker names a non-existent workstream, session has no pointer -> resolves null and the marker file is NOT deleted', () => {
+    const markerPath = path.join(tmpDir, '.planning', 'active-workstream');
+    fs.writeFileSync(markerPath, 'ghost-workstream\n');
+
+    const result = runGsdTools(['workstream', 'get'], tmpDir, { GSD_SESSION_KEY: 'stale-marker-session' });
+
+    assert.ok(result.success, `get failed: ${result.error}`);
+    assert.strictEqual(JSON.parse(result.output).active, null);
+    assert.ok(fs.existsSync(markerPath), 'a pointer-less session read must never delete the shared marker');
+    assert.strictEqual(fs.readFileSync(markerPath, 'utf-8'), 'ghost-workstream\n');
+  });
+
+  test('session pointer file exists but is whitespace-only -> treated as absent, inherits the marker', () => {
+    const markerPath = path.join(tmpDir, '.planning', 'active-workstream');
+    fs.writeFileSync(markerPath, 'beta\n');
+
+    runGsdTools(['workstream', 'set', 'alpha', '--raw'], tmpDir, { GSD_SESSION_KEY: 'whitespace-pointer-session' });
+    const sessionDir = getSessionPointerDir(tmpDir);
+    const sessionFile = getSessionPointerFileName('GSD_SESSION_KEY', 'whitespace-pointer-session');
+    fs.writeFileSync(path.join(sessionDir, sessionFile), '   \n');
+
+    const result = runGsdTools(['workstream', 'get', '--raw'], tmpDir, { GSD_SESSION_KEY: 'whitespace-pointer-session' });
+
+    assert.ok(result.success, `get failed: ${result.error}`);
+    assert.strictEqual(result.output, 'beta');
+  });
+
+  test('shared marker is whitespace-only, session pointer-less -> resolves null', () => {
+    const markerPath = path.join(tmpDir, '.planning', 'active-workstream');
+    fs.writeFileSync(markerPath, '   \n');
+
+    const result = runGsdTools(['workstream', 'get'], tmpDir, { GSD_SESSION_KEY: 'whitespace-marker-session' });
+
+    assert.ok(result.success, `get failed: ${result.error}`);
+    assert.strictEqual(JSON.parse(result.output).active, null);
+  });
+
+  test('shared marker file is empty, session pointer-less -> resolves null', () => {
+    const markerPath = path.join(tmpDir, '.planning', 'active-workstream');
+    fs.writeFileSync(markerPath, '');
+
+    const result = runGsdTools(['workstream', 'get'], tmpDir, { GSD_SESSION_KEY: 'empty-marker-session' });
+
+    assert.ok(result.success, `get failed: ${result.error}`);
+    assert.strictEqual(JSON.parse(result.output).active, null);
+  });
+
+  test('session pointer is stale (its workstream is deleted) while marker names a different, still-valid workstream -> resolves null, never falls through to inherit the marker', () => {
+    const markerPath = path.join(tmpDir, '.planning', 'active-workstream');
+    fs.writeFileSync(markerPath, 'beta\n');
+    runGsdTools(['workstream', 'set', 'alpha', '--raw'], tmpDir, { GSD_SESSION_KEY: 'stale-own-pointer-session' });
+    // eslint-disable-next-line local/no-raw-rmsync-in-tests -- mid-test fault injection: simulates a deleted workstream to exercise stale-pointer self-cleanup
+    fs.rmSync(path.join(tmpDir, '.planning', 'workstreams', 'alpha'), { recursive: true, force: true });
+
+    const result = runGsdTools(['workstream', 'get'], tmpDir, { GSD_SESSION_KEY: 'stale-own-pointer-session' });
+
+    assert.ok(result.success, `get failed: ${result.error}`);
+    assert.strictEqual(
+      JSON.parse(result.output).active,
+      null,
+      'a stale OWNED pointer must self-heal to null — it must not fall through to the shared marker just because it failed to resolve',
+    );
+    assert.strictEqual(fs.readFileSync(markerPath, 'utf-8'), 'beta\n', 'the shared marker must remain untouched');
+  });
+
+  // #3579 item 1: the #1912/#2028 workstream-mode fail-safe guards must
+  // distinguish "no marker/pointer anywhere" from "a marker exists but did
+  // not resolve" — asserted structurally (via --json-errors) per CONTRIBUTING,
+  // not by regexing the human-readable message.
+  test('init.progress fail-safe guard: no marker at all -> reason workstream_mode_none_active', () => {
+    const result = runGsdTools(['--json-errors', 'init', 'progress'], tmpDir);
+
+    assert.equal(result.success, false, 'must still refuse');
+    const payload = JSON.parse(result.error);
+    assert.equal(payload.reason, 'workstream_mode_none_active');
+  });
+
+  test('init.progress fail-safe guard: marker present but names a missing workstream dir -> reason workstream_mode_marker_unresolved, distinct message', () => {
+    const noneResult = runGsdTools(['--json-errors', 'init', 'progress'], tmpDir);
+    const nonePayload = JSON.parse(noneResult.error);
+
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'active-workstream'), 'ghost-workstream\n');
+    const unresolvedResult = runGsdTools(['--json-errors', 'init', 'progress'], tmpDir);
+
+    assert.equal(unresolvedResult.success, false, 'must still refuse');
+    const unresolvedPayload = JSON.parse(unresolvedResult.error);
+    assert.equal(unresolvedPayload.reason, 'workstream_mode_marker_unresolved');
+    assert.equal(unresolvedPayload.marker_value, 'ghost-workstream');
+    assert.equal(unresolvedPayload.marker_reason, 'missing_workstream_dir');
+    assert.notEqual(
+      unresolvedPayload.message,
+      nonePayload.message,
+      'the marker-present-but-unresolved diagnostic must differ from the no-marker-at-all diagnostic',
+    );
+  });
+
+  test('init.progress fail-safe guard: marker present but names an invalid workstream name -> reason workstream_mode_marker_unresolved, invalid_name', () => {
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'active-workstream'), 'bad/name\n');
+
+    const result = runGsdTools(['--json-errors', 'init', 'progress'], tmpDir);
+
+    assert.equal(result.success, false, 'must still refuse');
+    const payload = JSON.parse(result.error);
+    assert.equal(payload.reason, 'workstream_mode_marker_unresolved');
+    assert.equal(payload.marker_value, 'bad/name');
+    assert.equal(payload.marker_reason, 'invalid_name');
+  });
+});
+
 describe('pointer lifecycle hardening', () => {
  let tmpDir;