fix: harden workstream session routing fallback

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

@@ -22,10 +22,11 @@ const WORKSTREAM_SESSION_ENV_KEYS = [
   'WT_SESSION',
   'TMUX_PANE',
   'ZELLIJ_SESSION_NAME',
-  'TTY',
-  'SSH_TTY',
 ];
 
+let cachedControllingTtyToken = null;
+let didProbeControllingTtyToken = false;
+
 // ─── Path helpers ────────────────────────────────────────────────────────────
 
 /** Normalize a relative path to always use forward slashes (cross-platform). */
@@ -637,10 +638,14 @@ function sanitizeWorkstreamSessionToken(value) {
   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_/, '')}`;
+function probeControllingTtyToken() {
+  if (didProbeControllingTtyToken) return cachedControllingTtyToken;
+  didProbeControllingTtyToken = true;
+
+  // `tty` reads stdin. When stdin is already non-interactive, spawning it only
+  // adds avoidable failures on the routing hot path and cannot reveal a stable token.
+  if (!(process.stdin && process.stdin.isTTY)) {
+    return cachedControllingTtyToken;
   }
 
   try {
@@ -650,13 +655,31 @@ function getControllingTtyToken() {
     }).trim();
     if (ttyPath && ttyPath !== 'not a tty') {
       const token = sanitizeWorkstreamSessionToken(ttyPath.replace(/^\/dev\//, ''));
-      if (token) return `tty-${token}`;
+      if (token) cachedControllingTtyToken = `tty-${token}`;
     }
   } catch {}
 
-  return null;
+  return cachedControllingTtyToken;
 }
 
+function getControllingTtyToken() {
+  for (const envKey of ['TTY', 'SSH_TTY']) {
+    const token = sanitizeWorkstreamSessionToken(process.env[envKey]);
+    if (token) return `tty-${token.replace(/^dev_/, '')}`;
+  }
+
+  return probeControllingTtyToken();
+}
+
+/**
+ * Resolve a deterministic session key for workstream-local routing.
+ *
+ * Order:
+ * 1. Explicit runtime/session env vars (`GSD_SESSION_KEY`, `CODEX_THREAD_ID`, etc.)
+ * 2. Terminal identity exposed via `TTY` or `SSH_TTY`
+ * 3. One best-effort `tty` probe when stdin is interactive
+ * 4. `null`, which tells callers to use the legacy shared pointer fallback
+ */
 function getWorkstreamSessionKey() {
   for (const envKey of WORKSTREAM_SESSION_ENV_KEYS) {
     const raw = process.env[envKey];
@@ -685,16 +708,32 @@ function getSessionScopedWorkstreamFile(cwd) {
   };
 }
 
-function readActiveWorkstreamPointer(filePath, cwd) {
+function clearActiveWorkstreamPointer(filePath, cleanupDirPath) {
+  try { fs.unlinkSync(filePath); } catch {}
+
+  // Session-scoped pointers for a repo share one tmp directory. Only remove it
+  // when it is empty so clearing or self-healing one session never deletes siblings.
+  if (cleanupDirPath) {
+    try { fs.rmdirSync(cleanupDirPath); } catch {}
+  }
+}
+
+/**
+ * Pointer files are self-healing: invalid names or deleted-workstream pointers
+ * are removed on read so the session falls back to `null` instead of carrying
+ * silent stale state forward. Session-scoped callers may also prune an empty
+ * per-project tmp directory; shared `.planning/active-workstream` callers do not.
+ */
+function readActiveWorkstreamPointer(filePath, cwd, cleanupDirPath = null) {
   try {
     const name = fs.readFileSync(filePath, 'utf-8').trim();
     if (!name || !/^[a-zA-Z0-9_-]+$/.test(name)) {
-      try { fs.unlinkSync(filePath); } catch {}
+      clearActiveWorkstreamPointer(filePath, cleanupDirPath);
       return null;
     }
     const wsDir = path.join(planningRoot(cwd), 'workstreams', name);
     if (!fs.existsSync(wsDir)) {
-      try { fs.unlinkSync(filePath); } catch {}
+      clearActiveWorkstreamPointer(filePath, cleanupDirPath);
       return null;
     }
     return name;
@@ -716,7 +755,7 @@ function readActiveWorkstreamPointer(filePath, cwd) {
 function getActiveWorkstream(cwd) {
   const sessionScoped = getSessionScopedWorkstreamFile(cwd);
   if (sessionScoped) {
-    return readActiveWorkstreamPointer(sessionScoped.filePath, cwd);
+    return readActiveWorkstreamPointer(sessionScoped.filePath, cwd, sessionScoped.dirPath);
   }
 
   const sharedFilePath = path.join(planningRoot(cwd), 'active-workstream');
@@ -737,10 +776,7 @@ function setActiveWorkstream(cwd, name) {
     : path.join(planningRoot(cwd), 'active-workstream');
 
   if (!name) {
-    try { fs.unlinkSync(filePath); } catch {}
-    if (sessionScoped) {
-      try { fs.rmdirSync(sessionScoped.dirPath); } catch {}
-    }
+    clearActiveWorkstreamPointer(filePath, sessionScoped ? sessionScoped.dirPath : null);
     return;
   }
   if (!/^[a-zA-Z0-9_-]+$/.test(name)) {

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

@@ -24,6 +24,41 @@ GSD now prefers a session-scoped pointer keyed by runtime/session identity
 or the controlling TTY). This keeps concurrent sessions isolated while preserving
 legacy compatibility for runtimes that do not expose a stable session key.
 
+## Session Identity Resolution
+
+When GSD resolves the session-scoped pointer in step 3 above, it uses this order:
+
+1. Explicit runtime/session env vars such as `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`, and `ZELLIJ_SESSION_NAME`
+2. `TTY` or `SSH_TTY` if the shell/runtime already exposes the terminal path
+3. A single best-effort `tty` probe, but only when stdin is interactive
+
+If none of those produce a stable identity, GSD does not keep probing. It falls
+back directly to the legacy shared `.planning/active-workstream` file.
+
+This matters in headless or stripped environments: when stdin is already
+non-interactive, GSD intentionally skips shelling out to `tty` because that path
+cannot discover a stable session identity and only adds avoidable failures on the
+routing hot path.
+
+## Pointer Lifecycle
+
+Session-scoped pointers are intentionally lightweight and best-effort:
+
+- Clearing a workstream for one session removes only that session's pointer file
+- If that was the last pointer for the repo, GSD also removes the now-empty
+  per-project temp directory
+- If sibling session pointers still exist, the temp directory is left in place
+- When a pointer refers to a workstream directory that no longer exists, GSD
+  treats it as stale state: it removes that pointer file and resolves to `null`
+  until the session explicitly sets a new active workstream again
+
+GSD does not currently run a background garbage collector for historical temp
+directories. Cleanup is opportunistic at the pointer being cleared or self-healed,
+and broader temp hygiene is left to OS temp cleanup or future maintenance work.
+
 ## Routing Propagation
 
 All workflow routing commands include `${GSD_WS}` which: