Add a new /gsd changelog command that fetches releases from the GitHub API,
filters by version, and sends the raw changelog into the conversation for the
LLM to summarize the most important changes.
- New changelog.ts module: GitHub API fetch, semver filtering, body parsing
- Routing block in commands.ts with lazy import (same pattern as forensics)
- Tab completion in commands-bootstrap.ts TOP_LEVEL_SUBCOMMANDS
- Help text under VISIBILITY section in showHelp()
- No new npm dependencies — uses built-in fetch()
* refactor: replace recursive auto-dispatch with linear autoLoop, delete ~3k lines of dead code
Replace the complex recursive dispatch system (dispatchNextUnit, reentrancy
guards, stall detection, idempotency tracking, skip-depth machinery) with a
simple linear while(s.active) loop in auto-loop.ts.
Key changes:
- New auto-loop.ts with autoLoop(), runUnit(), resolveAgentEnd()
- Deleted auto-idempotency.ts, auto-stuck-detection.ts, session-lock.ts,
mechanical-completion.ts, progress-score.ts, auto-constants.ts, unit-id.ts
- Extracted WorktreeResolver class for worktree path resolution
- Added auto-worktree-sync.ts for worktree synchronization
- Simplified auto.ts from ~1400 lines to ~400 lines
- Fixed 9 TypeScript errors (NotifyCtx type widening, capture typing)
- Comprehensive test coverage: 32 auto-loop tests + worktree resolver/DB tests
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: address 6 audit findings in auto-loop refactor
1. CRITICAL: Move pendingResolve to AutoSession + queue orphaned agent_end
events instead of silently dropping them. Prevents permanent stalls when
error-recovery sendMessage retries fire between loop iterations.
2. HIGH: Scope pendingResolve per-session via _activeSession ref, preventing
concurrent /gsd auto sessions from corrupting each other's promises.
3. HIGH: Replace console.log in dispatchHookUnit with debugLog to prevent
hook prompt content (potentially containing secrets) from leaking to stdout.
4. HIGH: Restore parked milestone handling in state.ts — Phase 1 skips
parked milestones so they don't satisfy depends_on, Phase 2 registers
them as 'parked' status. Add 'parked' to MilestoneRegistryEntry type.
5. MEDIUM: Restore queuePhaseActive parameter in shouldBlockContextWrite
and re-export setQueuePhaseActive for guided-flow-queue.ts consumers.
6. MEDIUM: Add MAX_LOOP_ITERATIONS (500) lifetime cap to autoLoop to prevent
runaway loops when units alternate between IDs.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: resolve build breakers, add correctness fixes, and graduated recovery
Build breakers (CRITICAL):
- Restore unit-id.ts (deleted but still imported by complexity-classifier.ts, metrics.ts)
- Restore progress-score.ts (deleted but still imported by commands.ts, dashboard-overlay.ts, doctor.ts)
- Rewrite worktree-sync-milestones.test.ts to use new syncProjectRootToWorktree API
Correctness fixes (MEDIUM):
- Cap pendingAgentEndQueue to 3 entries to prevent unbounded growth from stale events
- Add milestoneId path traversal validation in WorktreeResolver
- Clear depthVerificationDone on session_start to prevent cross-session leaks in RPC mode
- Add verification gate for non-hook sidecar units (triage, quick-tasks)
- Remove dead handleAgentEnd import from index.ts
Graduated recovery (Jeremy's feedback):
- Blanket try/catch around loop body — one bad iteration no longer kills the session
- Graduated stuck recovery: at count 3 try artifact verification + cache invalidation,
at count 5 hard stop (was: binary stop at 5 with no recovery attempt)
- Graduated error recovery: 1st error retries, 2nd invalidates caches, 3rd stops
Test results: 32/32 auto-loop, 28/28 worktree-resolver, 11/11 sidecar-queue, tsc clean.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: restore copyWorktreeDb/reconcileWorktreeDb exports and fix loadToolApiKeys import
Two missing exports caused ~90% of the 120 pre-existing test failures:
1. copyWorktreeDb + reconcileWorktreeDb — imported by auto-worktree.ts but
never added to gsd-db.ts. Restored with the original implementations.
2. loadToolApiKeys — moved to commands-config.ts but index.ts still imported
from commands.ts. Fixed the import path.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: move loadToolApiKeys import to commands-config.js
loadToolApiKeys was moved to commands-config.ts but index.ts still
imported it from commands.ts, causing runtime failures in all tests
that transitively load the extension entry point.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: fix provider error assertion on windows
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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.
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.
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.
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)
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.
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>
* fix(gsd): skip non-artifact UAT dispatch in auto-mode
Non-artifact-driven UATs (human-experience, live-runtime, mixed) were
dispatched only to write a "surfaced-for-human-review" verdict, which
then blocked the verdict gate and killed auto-mode progression. Auto
now only dispatches artifact-driven UATs it can actually execute.
- checkNeedsRunUat returns null for non-artifact-driven UAT types
- Remove pauseAfterDispatch flag (always artifact-driven now)
- Strip human-review template path from run-uat prompt
- Remove dead pause-after-UAT logic from auto.ts
- Add test for non-artifact UAT skip + stale replay guard
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: update buildRunUatPrompt call in direct dispatch after signature change
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
