fix: isolate active workstream state per session

commands/gsd/workstreams.md

@@ -44,7 +44,9 @@ Display detailed phase breakdown and state information.
 
 ### switch
 Run: `node "$GSD_TOOLS" workstream set <name> --raw --cwd "$CWD"`
-Also set `GSD_WORKSTREAM` env var for the current session.
+Also set `GSD_WORKSTREAM` for the current session when the runtime supports it.
+If the runtime exposes a session identifier, GSD also stores the active workstream
+session-locally so concurrent sessions do not overwrite each other.
 
 ### progress
 Run: `node "$GSD_TOOLS" workstream progress --raw --cwd "$CWD"`

docs/USER-GUIDE.md

@@ -321,7 +321,7 @@ Workstreams let you work on multiple milestone areas concurrently without state
 
 ### How It Works
 
-Each workstream maintains its own `.planning/` directory subtree. When you switch workstreams, GSD swaps the active planning context so that `/gsd:progress`, `/gsd:discuss-phase`, `/gsd:plan-phase`, and other commands operate on that workstream's state.
+Each workstream maintains its own `.planning/` directory subtree. When you switch workstreams, GSD swaps the active planning context so that `/gsd:progress`, `/gsd:discuss-phase`, `/gsd:plan-phase`, and other commands operate on that workstream's state. Active context is session-scoped when the runtime exposes a stable session identifier, which prevents one terminal or AI instance from repointing another instance's `STATE.md`.
 
 This is lighter weight than `/gsd:new-workspace` (which creates separate repo worktrees). Workstreams share the same codebase and git history but isolate planning artifacts.
 

get-shit-done/bin/gsd-tools.cjs

@@ -235,7 +235,7 @@ async function main() {
   }
 
   // Optional workstream override for parallel milestone work.
-  // Priority: --ws flag > GSD_WORKSTREAM env var > active-workstream file > null (flat mode)
+  // Priority: --ws flag > GSD_WORKSTREAM env var > session-scoped pointer > shared legacy pointer > null
   const wsEqArg = args.find(arg => arg.startsWith('--ws='));
   const wsIdx = args.indexOf('--ws');
   let ws = null;

get-shit-done/bin/lib/core.cjs

@@ -3,10 +3,29 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
+const crypto = require('crypto');
 const { execSync, execFileSync, spawnSync } = require('child_process');
 const { MODEL_PROFILES } = require('./model-profiles.cjs');
 
+const WORKSTREAM_SESSION_ENV_KEYS = [
+  'GSD_SESSION_KEY',
+  'CODEX_THREAD_ID',
+  'CLAUDE_SESSION_ID',
+  'CLAUDE_CODE_SSE_PORT',
+  'OPENCODE_SESSION_ID',
+  'GEMINI_SESSION_ID',
+  'CURSOR_SESSION_ID',
+  'WINDSURF_SESSION_ID',
+  'TERM_SESSION_ID',
+  'WT_SESSION',
+  'TMUX_PANE',
+  'ZELLIJ_SESSION_NAME',
+  'TTY',
+  'SSH_TTY',
+];
+
 // ─── Path helpers ────────────────────────────────────────────────────────────
 
 /** Normalize a relative path to always use forward slashes (cross-platform). */
@@ -612,35 +631,125 @@ function planningPaths(cwd, ws) {
 
 // ─── Active Workstream Detection ─────────────────────────────────────────────
 
-/**
- * Get the active workstream name from .planning/active-workstream file.
- * Returns null if no active workstream or file doesn't exist.
- */
-function getActiveWorkstream(cwd) {
-  const filePath = path.join(planningRoot(cwd), 'active-workstream');
+function sanitizeWorkstreamSessionToken(value) {
+  if (value === null || value === undefined) return null;
+  const token = String(value).trim().replace(/[^a-zA-Z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
+  return token ? token.slice(0, 160) : null;
+}
+
+function getControllingTtyToken() {
+  for (const envKey of ['TTY', 'SSH_TTY']) {
+    const token = sanitizeWorkstreamSessionToken(process.env[envKey]);
+    if (token) return `tty-${token.replace(/^dev_/, '')}`;
+  }
+
+  try {
+    const ttyPath = execFileSync('tty', [], {
+      encoding: 'utf-8',
+      stdio: ['inherit', 'pipe', 'ignore'],
+    }).trim();
+    if (ttyPath && ttyPath !== 'not a tty') {
+      const token = sanitizeWorkstreamSessionToken(ttyPath.replace(/^\/dev\//, ''));
+      if (token) return `tty-${token}`;
+    }
+  } catch {}
+
+  return null;
+}
+
+function getWorkstreamSessionKey() {
+  for (const envKey of WORKSTREAM_SESSION_ENV_KEYS) {
+    const raw = process.env[envKey];
+    const token = sanitizeWorkstreamSessionToken(raw);
+    if (token) return `${envKey.toLowerCase().replace(/[^a-z0-9]+/g, '-')}-${token}`;
+  }
+
+  return getControllingTtyToken();
+}
+
+function getSessionScopedWorkstreamFile(cwd) {
+  const sessionKey = getWorkstreamSessionKey();
+  if (!sessionKey) return null;
+
+  const projectId = crypto
+    .createHash('sha1')
+    .update(path.resolve(planningRoot(cwd)))
+    .digest('hex')
+    .slice(0, 16);
+
+  const dirPath = path.join(os.tmpdir(), 'gsd-workstream-sessions', projectId);
+  return {
+    sessionKey,
+    dirPath,
+    filePath: path.join(dirPath, sessionKey),
+  };
+}
+
+function readActiveWorkstreamPointer(filePath, cwd) {
   try {
     const name = fs.readFileSync(filePath, 'utf-8').trim();
-    if (!name || !/^[a-zA-Z0-9_-]+$/.test(name)) return null;
+    if (!name || !/^[a-zA-Z0-9_-]+$/.test(name)) {
+      try { fs.unlinkSync(filePath); } catch {}
+      return null;
+    }
     const wsDir = path.join(planningRoot(cwd), 'workstreams', name);
-    if (!fs.existsSync(wsDir)) return null;
+    if (!fs.existsSync(wsDir)) {
+      try { fs.unlinkSync(filePath); } catch {}
+      return null;
+    }
     return name;
   } catch {
     return null;
   }
 }
 
+/**
+ * Get the active workstream name.
+ *
+ * Resolution priority:
+ * 1. Session-scoped pointer (tmpdir) when the runtime exposes a stable session key
+ * 2. Legacy shared `.planning/active-workstream` file when no session key is available
+ *
+ * The shared file is intentionally ignored when a session key exists so multiple
+ * concurrent sessions do not overwrite each other's active workstream.
+ */
+function getActiveWorkstream(cwd) {
+  const sessionScoped = getSessionScopedWorkstreamFile(cwd);
+  if (sessionScoped) {
+    return readActiveWorkstreamPointer(sessionScoped.filePath, cwd);
+  }
+
+  const sharedFilePath = path.join(planningRoot(cwd), 'active-workstream');
+  return readActiveWorkstreamPointer(sharedFilePath, cwd);
+}
+
 /**
  * Set the active workstream. Pass null to clear.
+ *
+ * When a stable session key is available, this updates a tmpdir-backed
+ * session-scoped pointer. Otherwise it falls back to the legacy shared
+ * `.planning/active-workstream` file for backward compatibility.
  */
 function setActiveWorkstream(cwd, name) {
-  const filePath = path.join(planningRoot(cwd), 'active-workstream');
+  const sessionScoped = getSessionScopedWorkstreamFile(cwd);
+  const filePath = sessionScoped
+    ? sessionScoped.filePath
+    : path.join(planningRoot(cwd), 'active-workstream');
+
   if (!name) {
     try { fs.unlinkSync(filePath); } catch {}
+    if (sessionScoped) {
+      try { fs.rmdirSync(sessionScoped.dirPath); } catch {}
+    }
     return;
   }
   if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
     throw new Error('Invalid workstream name: must be alphanumeric, hyphens, and underscores only');
   }
+
+  if (sessionScoped) {
+    fs.mkdirSync(sessionScoped.dirPath, { recursive: true });
+  }
   fs.writeFileSync(filePath, name + '\n', 'utf-8');
 }
 

get-shit-done/references/workstream-flag.md

@@ -9,8 +9,20 @@ parallel milestone work by multiple Claude Code instances on the same codebase.
 
 1. `--ws <name>` flag (explicit, highest priority)
 2. `GSD_WORKSTREAM` environment variable (per-instance)
-3. `.planning/active-workstream` file (shared, last-writer-wins)
-4. `null` — flat mode (no workstreams)
+3. Session-scoped active workstream pointer in temp storage (per runtime session / terminal)
+4. `.planning/active-workstream` file (legacy shared fallback when no session key exists)
+5. `null` — flat mode (no workstreams)
+
+## Why session-scoped pointers exist
+
+The shared `.planning/active-workstream` file is fundamentally unsafe when multiple
+Claude/Codex instances are active on the same repo at the same time. One session can
+silently repoint another session's `STATE.md`, `ROADMAP.md`, and phase paths.
+
+GSD now prefers a session-scoped pointer keyed by runtime/session identity
+(`GSD_SESSION_KEY`, `CODEX_THREAD_ID`, `CLAUDE_CODE_SSE_PORT`, terminal session IDs,
+or the controlling TTY). This keeps concurrent sessions isolated while preserving
+legacy compatibility for runtimes that do not expose a stable session key.
 
 ## Routing Propagation
 
@@ -29,7 +41,7 @@ This ensures workstream scope chains automatically through the workflow:
 ├── config.json         # Shared
 ├── milestones/         # Shared
 ├── codebase/           # Shared
-├── active-workstream   # Points to current ws
+├── active-workstream   # Legacy shared fallback only
 └── workstreams/
     ├── feature-a/      # Workstream A
     │   ├── STATE.md
@@ -50,6 +62,12 @@ This ensures workstream scope chains automatically through the workflow:
 node gsd-tools.cjs state json --ws feature-a
 node gsd-tools.cjs find-phase 3 --ws feature-b
 
+# Session-local switching without --ws on every command
+GSD_SESSION_KEY=my-terminal-a node gsd-tools.cjs workstream set feature-a
+GSD_SESSION_KEY=my-terminal-a node gsd-tools.cjs state json
+GSD_SESSION_KEY=my-terminal-b node gsd-tools.cjs workstream set feature-b
+GSD_SESSION_KEY=my-terminal-b node gsd-tools.cjs state json
+
 # Workstream CRUD
 node gsd-tools.cjs workstream create <name>
 node gsd-tools.cjs workstream list

tests/helpers.cjs

@@ -7,6 +7,22 @@ const fs = require('fs');
 const path = require('path');
 
 const TOOLS_PATH = path.join(__dirname, '..', 'get-shit-done', 'bin', 'gsd-tools.cjs');
+const TEST_ENV_BASE = {
+  GSD_SESSION_KEY: '',
+  CODEX_THREAD_ID: '',
+  CLAUDE_SESSION_ID: '',
+  CLAUDE_CODE_SSE_PORT: '',
+  OPENCODE_SESSION_ID: '',
+  GEMINI_SESSION_ID: '',
+  CURSOR_SESSION_ID: '',
+  WINDSURF_SESSION_ID: '',
+  TERM_SESSION_ID: '',
+  WT_SESSION: '',
+  TMUX_PANE: '',
+  ZELLIJ_SESSION_NAME: '',
+  TTY: '',
+  SSH_TTY: '',
+};
 
 /**
  * Run gsd-tools command.
@@ -21,7 +37,7 @@ const TOOLS_PATH = path.join(__dirname, '..', 'get-shit-done', 'bin', 'gsd-tools
 function runGsdTools(args, cwd = process.cwd(), env = {}) {
   try {
     let result;
-    const childEnv = { ...process.env, ...env };
+    const childEnv = { ...process.env, ...TEST_ENV_BASE, ...env };
     if (Array.isArray(args)) {
       result = execFileSync(process.execPath, [TOOLS_PATH, ...args], {
         cwd,

tests/workstream.test.cjs

@@ -65,6 +65,80 @@ describe('planningDir workstream awareness via env var', () => {
   });
 });
 
+describe('session-scoped active workstream routing', () => {
+  let tmpDir;
+
+  before(() => {
+    tmpDir = createTempProject();
+
+    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`);
+    }
+  });
+
+  after(() => cleanup(tmpDir));
+
+  test('stores active workstream per session instead of mutating shared pointer', () => {
+    const alphaSet = runGsdTools(['workstream', 'set', 'alpha', '--raw'], tmpDir, { GSD_SESSION_KEY: 'session-alpha' });
+    const betaSet = runGsdTools(['workstream', 'set', 'beta', '--raw'], tmpDir, { GSD_SESSION_KEY: 'session-beta' });
+
+    assert.ok(alphaSet.success, `alpha set failed: ${alphaSet.error}`);
+    assert.ok(betaSet.success, `beta set failed: ${betaSet.error}`);
+    assert.ok(!fs.existsSync(path.join(tmpDir, '.planning', 'active-workstream')),
+      'shared active-workstream file should not be used when session keys are available');
+  });
+
+  test('different sessions resolve different active workstreams without --ws', () => {
+    const alpha = runGsdTools(['workstream', 'get', '--raw'], tmpDir, { GSD_SESSION_KEY: 'session-alpha' });
+    const beta = runGsdTools(['workstream', 'get', '--raw'], tmpDir, { GSD_SESSION_KEY: 'session-beta' });
+
+    assert.ok(alpha.success, `alpha get failed: ${alpha.error}`);
+    assert.ok(beta.success, `beta get failed: ${beta.error}`);
+    assert.strictEqual(alpha.output, 'alpha');
+    assert.strictEqual(beta.output, 'beta');
+  });
+
+  test('session-scoped pointer ignores legacy shared active-workstream file', () => {
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'active-workstream'), 'beta\n');
+
+    const alpha = runGsdTools(['workstream', 'get', '--raw'], tmpDir, { GSD_SESSION_KEY: 'session-alpha' });
+    const shared = runGsdTools(['workstream', 'get', '--raw'], tmpDir);
+
+    assert.ok(alpha.success, `session-scoped get failed: ${alpha.error}`);
+    assert.ok(shared.success, `legacy get failed: ${shared.error}`);
+    assert.strictEqual(alpha.output, 'alpha');
+    assert.strictEqual(shared.output, 'beta');
+  });
+
+  test('state commands route to the session-scoped workstream automatically', () => {
+    const alpha = runGsdTools(['state', 'json', '--raw'], tmpDir, { GSD_SESSION_KEY: 'session-alpha' });
+    const beta = runGsdTools(['state', 'json', '--raw'], tmpDir, { GSD_SESSION_KEY: 'session-beta' });
+
+    assert.ok(alpha.success, `alpha state failed: ${alpha.error}`);
+    assert.ok(beta.success, `beta state failed: ${beta.error}`);
+    const alphaState = JSON.parse(alpha.output);
+    const betaState = JSON.parse(beta.output);
+    assert.strictEqual(alphaState.status, 'Alpha active');
+    assert.strictEqual(betaState.status, 'Beta active');
+  });
+
+  test('clearing one session does not clear another session pointer', () => {
+    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' });
+
+    assert.ok(clearAlpha.success, `clear alpha failed: ${clearAlpha.error}`);
+    assert.ok(alpha.success, `alpha get after clear failed: ${alpha.error}`);
+    assert.ok(beta.success, `beta get after alpha clear failed: ${beta.error}`);
+
+    const cleared = JSON.parse(alpha.output);
+    assert.strictEqual(cleared.active, null);
+    assert.strictEqual(beta.output, 'beta');
+  });
+});
+
 // ─── Workstream CRUD ────────────────────────────────────────────────────────
 
 describe('workstream create', () => {