Extract the duplicated file lock mechanism from auth-storage.ts and
session-manager.ts into a shared lock-utils.ts module.
- acquireLockSyncWithRetry(): throwing variant (used by auth-storage)
- tryAcquireLockSync(): non-throwing variant (used by session-manager)
- acquireLockAsync(): async lock with retries and staleness detection
Removes ~55 lines of duplicated retry-loop logic. The shared module
also provides a foundation for deduplicating identical patterns in
settings-manager.ts and models-json-writer.ts.
- Replace dedupePrompts() and dedupeThemes() with generic dedupeResources<T>()
that accepts getName/getPath/resourceType callbacks
- Replace discoverSystemPromptFile() and discoverAppendSystemPromptFile() with
generic discoverFileInSearchPaths(filename)
- Import ResourceCollision type for use in dedupeResources signature
- Net reduction of 24 lines (868 → 844) with elimination of duplicated logic
Release session locks on bootstrap abort paths and reset same-process lock state before re-acquiring so stale proper-lockfile callbacks cannot poison a fresh auto-mode session. Adds regression coverage for bootstrap cleanup and re-entrant lock acquisition.
Move duplicated patterns from compaction.ts and branch-summarization.ts
into shared utilities in utils.ts:
- getMessageFromEntry(): unified entry-to-message conversion with
optional toolResult skipping for branch summarization
- collectMessages(): replaces three identical for-loops that collect
AgentMessages from entry ranges
- extractTextContent(): replaces five instances of the
.filter(text).map(text).join() pattern
- createSummarizationMessage(): replaces three identical user-message
construction blocks for LLM summarization calls
Net reduction of ~90 lines of duplication.
- toPosixPath: remove private copies in skills.ts and package-manager.ts,
import from canonical utils/path-display.ts
- ZERO_USAGE: export from agent-loop.ts, replace inline zero-usage
objects in agent.ts and proxy.ts
- shortenPath: extract to shared modes/interactive/utils/shorten-path.ts,
import in tool-execution.ts and session-selector.ts
Extract the duplicated loop pattern (create context, iterate extensions,
iterate handlers, try/catch, emitError) into a private invokeHandlers()
helper. Each emit method is now a thin wrapper that delegates the
iteration to invokeHandlers and provides only its result-processing
callback. Net reduction of ~124 lines with identical runtime behavior.
Replace 7 individual ToolResultEvent type guards (isBashToolResult,
isReadToolResult, etc.) with a unified isToolResultEventType() function,
mirroring the existing isToolCallEventType() pattern.
Inline 14 handler type aliases (SendMessageHandler, SetModelHandler, etc.)
directly into the ExtensionActions interface since they were only used there
and added no semantic value.
Update documentation examples to use the new unified guard.
On older Linux distributions (e.g., RHEL 8 with older glibc), the native
Rust addon fails to load. The proxy throws on every function call, but
wrapTextWithAnsi and visibleWidth in pi-tui had no JS fallback — causing
an uncaught crash during TUI rendering.
Fix: Both functions now catch native throws and fall back to JS
implementations (simple word-wrap and ANSI-strip length).
Fixes#1418
getSessionStats() calculated cost by summing usage from assistant messages
in state.messages. After auto-compaction, pre-compaction messages are
replaced by a compactionSummary with no usage field — dropping the cost.
Fix: Added cumulative accumulators (_cumulativeCost, _cumulativeInputTokens,
_cumulativeOutputTokens, _cumulativeToolCalls) that are incremented on
every assistant message event, independent of the message array.
getSessionStats() now returns max(array-sum, cumulative) to ensure
monotonically non-decreasing values.
Fixes#1423
Three CI regressions from the initial commit:
1. doctor.test.ts "two blocking errors" assertion broke (expected 2, got 3):
The provider check fired on any project with an active milestone, including
CI environments with no API key. Fix: change provider_key_missing severity
from "error" to "warning". A missing key is advisory — it blocks future
dispatch but doesn't corrupt existing state, analogous to env_git_remote.
2. doctor-runtime.test.ts stranded_lock_directory fails on Windows:
proper-lockfile uses advisory file locking on Windows, not the directory-based
mechanism (.gsd.lock/). The check and tests are POSIX-specific. Fix: skip
both stranded_lock_directory tests on Windows with process.platform guard,
same pattern used by worktree and branch tests.
3. doctor-checks.ts used root.split("/").pop() which is not cross-platform:
Windows paths use backslash separators. Fix: replace with basename(root)
from node:path which is platform-aware. Also add basename to imports.
Added scripts/generate-openrouter-models.mjs that fetches the full model
list from OpenRouter's API and generates TypeScript entries matching the
existing models.generated.ts format. Run with:
node scripts/generate-openrouter-models.mjs > /tmp/openrouter.ts
Updated the OpenRouter section in models.generated.ts from 241 → 350
models, including all nvidia/nemotron variants requested in the issue.
Fixes#1407
Closes the highest-impact gaps identified in the /gsd doctor deep-dive analysis.
**1. Wire provider checks into runGSDDoctor()**
doctor-providers.ts existed and worked but was never called from the main
doctor run. Units could dispatch into guaranteed API failures with no warning.
Now runProviderChecks() is called in runGSDDoctor() and converts required-provider
errors/warnings into DoctorIssue entries with codes:
- provider_key_missing (error)
- provider_key_backedoff (warning)
**2. Stranded lock directory detection (doctor-checks.ts)**
proper-lockfile creates a .gsd.lock/ directory as the OS-level lock mechanism.
After SIGKILL or hard crash, this directory can remain stranded, blocking all
future auto-mode sessions from acquiring the lock (#1245 pattern). Doctor now:
- Detects .gsd.lock/ existing without a live process holding it
- Reports as stranded_lock_directory (error, fixable)
- Auto-fix removes the stranded directory
**3. Integration branch existence check (doctor-checks.ts + doctor-proactive.ts)**
When a milestone records an integration branch and that branch is later deleted
or renamed, merge-back will fail silently at the end of the milestone. Doctor now:
- Checks each active milestone's stored integration branch exists in git
- Reports as integration_branch_missing (error, not auto-fixable)
- preDispatchHealthGate blocks dispatch if the active milestone's integration
branch is missing, preventing work from being dispatched into a dead end
**4. Orphaned worktree directory detection (doctor-checks.ts)**
Worktree removal can fail after a branch delete, leaving a .gsd/worktrees/<name>/
directory that is no longer registered with git. Re-creating the same name fails
with "already exists". Doctor now:
- Compares .gsd/worktrees/ entries against git worktree list
- Reports unregistered directories as worktree_directory_orphaned (warning, fixable)
- Auto-fix removes the orphaned directory
Tests: all new codes covered with detection + fix assertions, including
false-positive safety cases (live lock holder, registered worktrees,
existing integration branch). All 1843 existing tests still pass.
* fix: sync worktree completion artifacts back to external state before merge (#1412)
When a worktree's .gsd/ was a real directory (not symlinked to external
state), milestone completion artifacts (SUMMARY, VALIDATION, updated
ROADMAP) were written locally but never synced back. The project root's
deriveState() read from external state and found no SUMMARY — reporting
the milestone as incomplete.
Changes:
- auto-worktree.ts: Added syncWorktreeStateBack() that copies milestone
and slice .md files from worktree .gsd/ to the main external state dir
- auto.ts: Call syncWorktreeStateBack() in tryMergeMilestone before the
git merge, ensuring artifacts are visible from the project root
Fixes#1412
* fix: emit agent_end after abort during tool execution (#1414)
When a user aborts a turn while a tool call is running, the abort RPC
succeeds but agent_end was never emitted. RPC consumers tracking turn
lifecycle via events got stuck in a 'streaming' state permanently.
Fix: After abort() + waitForIdle(), emit a synthetic agent_end if the
agent is no longer streaming. This ensures consumers always see the
turn-complete signal regardless of how the turn ended.
Fixes#1414
guided-flow.ts showed 'Interrupted Session Detected' whenever auto.lock
existed, without checking if the lock was written by the current process.
This caused infinite prompt loops when the current session's own lock
triggered the crash detection.
Fix: Added crashLock.pid !== process.pid check, matching the guard in
auto-start.ts.
Also includes test fixes:
- repo-identity-worktree: macOS /var canonicalization
- resource-loader: partial-build dist/resources fallback
- file-watcher: init delay + timeout for timing stability
Fixes#1398
Two root causes for the false "Interrupted Session Detected" prompt
that appears every time /gsd is run after a normal exit:
1. guided-flow.ts showed the crash recovery menu even for bootstrap
crashes (unitType="starting", unitId="bootstrap", completedUnits=0)
where no work was lost. Now these are silently discarded — the menu
only appears when real auto-mode work was interrupted.
2. session-lock.ts exit handler cleaned the OS lock directory
(.gsd.lock/) but not the auto.lock metadata file. On next startup,
readCrashLock() found the stale file and triggered false recovery.
Now the exit handler also removes auto.lock.
- mergePreferences(): add auto_visualize and auto_report (both were
silently dropped when a project prefs file existed alongside global)
- preferences-validation.ts: add validation blocks for auto_visualize,
auto_report, compression_strategy, and context_selection — all four
were in KNOWN_PREFERENCE_KEYS and the GSDPreferences interface but
accepted any value without type-checking
- serializePreferencesToFrontmatter orderedKeys: add skill_staleness_days,
dynamic_routing, token_profile, phases, parallel, auto_visualize,
auto_report, verification_commands, verification_auto_fix,
verification_max_retries, search_provider, compression_strategy,
context_selection — these were falling through to the arbitrary-order
fallback loop instead of appearing in consistent positions
- preferences-reference.md: document git.auto_pr, git.pr_target_branch,
search_provider, compression_strategy, context_selection; add
deprecation notices for git.commit_docs and git.merge_to_main
- tests/preferences.test.ts: two new test cases covering all four newly
validated fields (valid values pass, invalid values produce errors)
When using a reasoning model (o1, o3, o4-mini, etc.) without explicitly
setting reasoningEffort or reasoningSummary, the include param was not
set. OpenAI returns a bare rs_... reasoning item ID which gets stored in
thinkingSignature and replayed in the next turn. Since store is false,
OpenAI cannot find the rs_... item server-side and returns a 404.
Fix: move params.include = ["reasoning.encrypted_content"] outside the
reasoningEffort/reasoningSummary guard so it is always set for any
reasoning model. This ensures the encrypted blob is returned and can be
replayed correctly without needing server-side storage.
smartStage() was excluding the entire .gsd/ directory from git staging,
which is correct when .gsd/ is symlinked to external state. But on
Windows (junction links) or projects where .gsd/ is git-tracked (not
gitignored), this caused a mid-milestone behavioral discontinuity:
1. One-time cleanup removes runtime files from the index
2. After cleanup, nativeAddAll() + nativeResetPaths('.gsd/') causes ALL
.gsd/ files to be unstaged — including milestone artifacts
3. autoCommit returns null (nothing staged) for the rest of the milestone
4. Work continues silently with no commits, no errors, no warnings
5. Worktree teardown loses all uncommitted .gsd/ artifacts
Fix: replace the blanket '.gsd/' exclusion with targeted RUNTIME_EXCLUSION_PATHS.
Milestone artifacts (.gsd/milestones/, preferences.md, DECISIONS.md, etc.)
are now committed normally when they're tracked. When .gsd/ is in .gitignore
(the default), git add -A already skips it — the reset is a harmless no-op.
Updated git-service.test.ts to verify the new behavior: runtime files
excluded, milestone artifacts committed.
Fixes#1326
When a GSD session crashes hard (SIGKILL, OOM, etc.) without running its
exit handler, the proper-lockfile OS lock directory (.gsd.lock/) is left
stranded. On the next /gsd auto resume, acquireSessionLock detects the dead
PID, cleans up the stale directory, and re-acquires via the retry path.
10 seconds later, proper-lockfile's update timer fires. Due to a subtle
interaction between the synchronous fs adapter (lockSync / toSyncOptions)
and the setTimeout boundary in Node.js v25+, the ECOMPROMISED error
propagates up through the synchronous callback chain and becomes an
uncaught exception — even though the onCompromised callback sets
_lockCompromised = true without throwing.
The _gsdEpipeGuard uncaughtException handler only handled EPIPE, so it
re-threw ECOMPROMISED, crashing the process. Each crash wrote a new
"interrupted session" record, causing an infinite crash loop on resume.
Two fixes:
1. index.ts: Handle ECOMPROMISED in _gsdEpipeGuard. Exit with code 1
(non-zero to signal failure) so the process.once("exit") handler runs
and removes the lock directory, allowing the next session to start clean.
2. session-lock.ts: The retry path's onCompromised was missing
`_releaseFunction = null`, unlike the primary path. This left the
release function pointer live after compromise, causing validateSessionLock
to return true and preventing graceful stop detection. Now matches primary.
10 tests that run against the installed gsd binary after npm publish:
1. headless query returns valid JSON
2. Empty project → pre-planning phase
3. Milestone with roadmap → planning phase
4. All tasks done → summarizing phase
5. Complete milestone → complete phase
6. Stale auto.lock doesn't block --version
7. Crash recovery query works with stale lock
8. Non-TTY exits quickly with clean error
9. Version skew detected before TTY check
10. --help works (native addon loads or falls back)
Wired into pipeline.yml test-verify job after fixture tests
and before @next promotion.
These catch the state machine / infrastructure bugs from #1308
that unit tests can't reach — they exercise deriveState through
the real gsd binary with real .gsd/ directory structures.
Part of #1308
Replaces 30+ inline `unitId.split("/")` + destructuring patterns across
16 production files with a single `parseUnitId()` helper that returns
`{ milestone, slice?, task? }`. If the unit ID format ever changes,
only one function needs updating.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The retry lock acquisition path (from stale lock recovery in #1251)
used a 5-minute stale threshold and no onCompromised handler, while
the primary path used 30 minutes and a graceful flag-based handler.
This mismatch meant locks acquired via the retry path would throw
ECOMPROMISED (uncaught, crashes process) if the event loop stalled
for >5 minutes — which happens during long LLM operations.
Fixed:
- Stale timeout: 300_000 → 1_800_000 (matches primary)
- Added onCompromised handler (sets _lockCompromised flag)
- Added process.on('exit') safety net (matches primary)
Also: reporter is on Node v25.6.1 which is unsupported — GSD requires
Node >=22.0.0 with 24 LTS recommended.
Fixes#1304
makeTreeWritable used statSync which follows symlinks. On NixOS and
nix-darwin, ~/.gsd/agent/bin/ contains symlinks to the immutable Nix
store (/run/current-system/sw/bin/). Attempting to chmod those targets
crashed GSD on startup with EPERM.
Changes:
- Use lstatSync instead of statSync — detects symlinks without
following them
- Skip symlinks entirely (they don't carry own permissions, targets
may be immutable)
- Added try/catch around chmodSync as safety net for any remaining
permission errors on unusual filesystems
Secondary analysis: rmSync with force:true already handles symlinks
correctly (removes the link, not the target). cpSync with force:true
replaces symlinks with regular files (desired behavior for resource
sync).
Fixes#1298
Consolidate the repeated `err instanceof Error ? err.message : String(err)`
pattern into a single `getErrorMessage(err)` utility. Reduces visual noise in
catch blocks across 20 files in the GSD extension.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: consolidate DB-fallback inline functions in auto-prompts
Extract shared inlineFromDbOrFile() helper that encapsulates the
repeated pattern of checking DB availability, dynamically importing
context-store, running a query, formatting results, and falling back
to the filesystem. The three public functions (inlineDecisionsFromDb,
inlineRequirementsFromDb, inlineProjectFromDb) become thin wrappers
that pass only the differing query/format logic as a callback.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: update source-level test to match refactored DB-fallback function name
The context-compression test greps auto-prompts.ts source for
`inlineGsdRootFile(base, "project.md"` which was replaced by
`inlineProjectFromDb(base)` in the consolidation refactor.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
