npm ≥7 suppresses lifecycle script output by default, so the clack
banner/spinner was invisible during `npm install -g`. The user-facing
onboarding experience already lives at first `gsd` launch (onboarding.ts),
making the postinstall UI redundant dead code.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Follow-up to #774. When GSD runs in worktree isolation mode,
completed-units.json can fragment across project root and worktree
locations. If a session crashes or the worktree is removed after
milestone merge, keys written to the worktree are lost — causing
already-completed units to be re-dispatched.
Two fixes:
1. syncStateToProjectRoot() now performs a set-union merge of
completed-units.json from worktree into project root.
2. After worktree entry at startup, loadPersistedKeys() runs against
both project root and worktree so the in-memory completedKeySet
contains the union of both locations.
Co-authored-by: Lex Christopherson <lex@glittercowboy.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: interactive update prompt on startup (#770)
When a newer version of gsd-pi is available, show an interactive
prompt at startup with two options:
[1] Update now (runs npm install -g gsd-pi@latest)
[2] Skip
- Adds checkAndPromptForUpdates() to update-check.ts
- Reuses existing 24h cache so the registry is hit at most once/day
- Shows a boxed banner with current → latest versions
- Runs npm install -g gsd-pi@latest if the user picks [1]
- Exits after a successful update so the user relaunches with the new build
- Cleans up stdin state (listeners + raw mode) so the TUI starts cleanly
- Updates cli.ts to call checkAndPromptForUpdates() instead of the
fire-and-forget checkForUpdates() in interactive mode
- Skipped in print/RPC/MCP/headless modes (isPrintMode guard)
* fix: update-check prompt cleanup and robustness (#770)
- Remove duplicate NPM_PACKAGE constant (was shadowing NPM_PACKAGE_NAME)
- Fix hardcoded box width: measure visible text width dynamically so the
border aligns correctly for any version string length
- Add 30s timeout to rl.question so the prompt auto-skips in non-TTY
or piped-stdin edge cases that slip past the isPrintMode guard
* fix: address review feedback on update prompt (#770)
Three issues from @glittercowboy's review:
1. Box rendering bug: mid line was built as '║' + content + '║' then
sliced with .slice(1,-1) which cuts into ANSI escape sequences.
Fix: build midContent without delimiters and wrap with chalk.yellow('║')
directly, keeping a separate plain-text midVisible for width measurement.
2. Missing TTY guard: !isPrintMode alone isn't sufficient — a piped
stdin without --print would sit waiting 30s silently.
Fix: gate checkAndPromptForUpdates() on process.stdin.isTTY; fall back
to the passive checkForUpdates() banner for non-TTY interactive mode.
3. Dead import: checkForUpdates was imported but unused after the
previous refactor. Now used again as the non-TTY fallback — no
dead code.
* fix: downgrade missing_tasks_dir to warning for completed slices (#726)
When a worktree is removed and artifacts are rebuilt, tasks/ directories
aren't recreated. For completed slices this is cosmetic scaffolding, not
a structural error. Downgrade severity from "error" to "warning" so
completed milestones can render in /gsd visualize.
Also skip the missing_slice_plan warning entirely for completed slices,
since a plan file serves no purpose after completion.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: use slice.done instead of non-existent frontmatter.status
The SummaryFrontmatter type doesn't have a `status` property.
Use `slice.done` from the roadmap parser instead, which is the
canonical completion signal already available in scope.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When auto-mode pauses due to a rate limit, schedule automatic resumption
after the rate limit window elapses. Shows a countdown notification so
the user knows what's happening. Non-rate-limit errors still pause
indefinitely for manual intervention.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Three fixes for the worktree isolation stuck-state bug:
1. selfHealRuntimeRecords on initial start used the function parameter
`base` (main project root) instead of `basePath` (worktree path after
entry). This meant stale runtime records in the worktree were never
found or healed, leaving dispatched records that block auto-mode.
2. syncStateToProjectRoot now copies runtime/units/ records alongside
milestone data. This provides defense-in-depth: even if selfHeal runs
before worktree re-entry, stale records from a prior sync are visible.
3. initMetrics and initRoutingHistory also corrected from `base` to
`basePath` — same class of bug (stale function parameter after
worktree entry).
Adds test verifying selfHealRuntimeRecords resolves artifacts and clears
records correctly when pointed at a worktree base path.
Add three remaining features:
1. Dashboard multi-session view: New worker registry
(subagent/worker-registry.ts) tracks active parallel subagent sessions
with batch grouping and status lifecycle. Dashboard overlay now renders
a "Parallel Workers" section showing per-batch worker status with
agent names, task previews, and elapsed time.
2. Budget approach notification at 80%: Added 80% threshold to the
existing 75/90/100 budget alert levels. Fires an "Approaching budget
ceiling" notification with desktop alert at the 80% mark, giving
users earlier warning before hitting enforcement thresholds.
3. End-to-end testing across milestones: New E2E test validates parallel
worker lifecycle across M001/M002 milestones, metrics accumulation,
full budget alert progression (0→75→80→90→100), cost prediction with
multi-milestone data, and combined worker+budget scenarios.
Worker registry unit tests cover registration, batch grouping, status
updates, and edge cases.
Worker spawning (parallel-orchestrator.ts):
- spawnWorker() creates child processes via spawn() with
GSD_MILESTONE_LOCK env var for state isolation
- GSD_PARALLEL_WORKER env var prevents nested parallel sessions
- Workers run `gsd --print "/gsd auto"` in their worktree cwd
- Exit handler updates worker state on completion/crash
- Graceful error handling for spawn failures (ENOENT, etc.)
- SIGTERM sent on stopParallel for immediate process termination
Worktree creation:
- createMilestoneWorktree() creates git worktrees using
milestone/<MID> branch naming without chdir (coordinator stays put)
- Reuses existing milestone branches to preserve prior work
- Runs post-create hooks for user scripts (.env copy, etc.)
GSD_MILESTONE_LOCK in state.ts:
- deriveState() filters to only the locked milestone
- getActiveMilestoneId() short-circuits when lock is set
- Complete worker isolation — each process sees one milestone
Signal consumption in auto.ts:
- handleAgentEnd() checks for coordinator signals between units
- Responds to "stop" and "pause" signals immediately
/gsd parallel merge command:
- Merge specific or all completed milestones back to main
976/976 full test suite passing, zero regressions.
GSD_MILESTONE_LOCK in state.ts:
- deriveState() filters milestoneIds to only the locked milestone
- getActiveMilestoneId() short-circuits when lock is set
- Each parallel worker sees only its assigned milestone
Signal consumption in auto.ts:
- handleAgentEnd() checks for coordinator signals before dispatching
- Responds to "stop" (calls stopAuto) and "pause" (calls pauseAuto)
- Only active when GSD_MILESTONE_LOCK env var is set
/gsd parallel merge command:
- /gsd parallel merge [mid] — merge specific or all completed milestones
- Wired into commands.ts with argument completions
Worker spawning stub:
- spawnWorker() validates state and documents the implementation plan
- Actual process forking deferred to auto-mode integration
976/976 full test suite passing, zero regressions.
Two compounding bugs caused auto-mode to loop infinitely after stopping
and restarting when a worktree with committed progress existed:
Bug 1: copyPlanningArtifacts overwrites worktree state on restart
When auto-mode restarts and the milestone branch exists (worktree dir was
removed but branch preserved), createAutoWorktree re-attaches the worktree
to the existing branch — git correctly checks out the committed state with
[x] checkboxes. But then copyPlanningArtifacts unconditionally copies the
project root's .gsd/milestones/ into the worktree, overwriting the correct
[x] with stale [ ] from the root (which isn't always fully synced).
Fix: Skip copyPlanningArtifacts when branchExists is true. The branch
checkout already has the correct artifacts from committed work.
Bug 2: deriveState reads stale content from SQLite DB
deriveState had a DB-first content loading path that read artifact content
from the SQLite artifacts table. This table was populated once during
migrateFromMarkdown and never updated when files changed on disk (roadmap
checkbox updates, plan changes, etc.). Even after fixing files on disk,
deriveState returned stale DB content, keeping the state machine stuck.
Fix: Remove the DB content loading path from deriveState entirely. The
native Rust batch parser (nativeBatchParseGsdFiles) reads all .md files
in one call and is fast enough. The DB is still used for structured queries
(decisions, requirements) but no longer as a content cache for state
derivation.
Updated derive-state-db.test.ts Test 5 to write requirements to disk
instead of testing the now-removed DB-only content path.
The reason parameter was added to stopAuto() but the reasonSuffix
variable derived from it was never declared, causing TS2304 errors.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove the version-match early return in initResources() that skipped
resource sync when versions matched. This allowed the runtime at
~/.gsd/agent/extensions/ to drift from the bundled resources when
individual files were manually copied or leftover from a newer version.
Also adds rmSync of bundled subdirectories before each cpSync to remove
stale files that exist only in the runtime. User-created extension
directories are preserved.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
stopAuto() now accepts an optional `reason` parameter that is included
in the session summary — every stop is self-documenting instead of
showing a generic "Auto-mode stopped" message.
Also replaces the catch-all `!mid` check with registry-aware logic that
distinguishes "all complete" from "blocked" and "unexpected no active
milestone" (with diagnostic output). Adds midTitle recovery fallback
when title regex strips to empty string.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When mergeMilestoneToMain runs from a worktree context, main is already
checked out at the project root. The unconditional git checkout main
fails with "already used by worktree" because git refuses to checkout a
branch that is active in another worktree.
Skip the checkout when the integration branch is already current at the
project root, which is always the case in worktree-mode merges.
Resolve conflicts between #699 (empty scaffold rejection) and #739
(task plan file verification) in auto-dispatch.ts imports and
auto-recovery.test.ts tests.
- auto-dispatch.ts: merged imports from both branches (resolveTaskFile
from #739, resolveMilestonePath/buildMilestoneFileName from main)
- auto-recovery.test.ts: included all tests from both #699 (empty
scaffold, actual tasks, completed tasks) and #739 (all task plans
exist, missing task plan, no tasks). Updated #699 tests to create
task plan files alongside slice plans to satisfy #739's verification.
Updated #739 "no tasks" test to expect false per #699's requirement
that plans must have task entries.
- auto-recovery.ts: auto-merged cleanly, both checks coexist
All 26 recovery tests pass. Full build clean.
Add a `validating-milestone` phase that runs BEFORE `completing-milestone`
to reconcile planned work against delivered work. The validator checks
success criteria, slice deliverables, cross-slice integration, and
requirement coverage before allowing milestone completion.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- bg-shell/types: add compiled union regexes (ERROR/WARNING/READINESS/BUILD/TEST)
built once at module load; add LINE_DEDUP_MAX constant (500); add
stdoutLineCount/stderrLineCount tracked fields to BgProcess; export
PORT_PATTERN_SOURCE string to avoid .source access per line
- bg-shell/output-formatter: analyzeLine uses union regexes instead of
.some(p => p.test(line)) across 5 pattern arrays; PORT_PATTERN no longer
reconstructed via new RegExp() on every line; lineDedup Map now has LRU
eviction at LINE_DEDUP_MAX entries (prevents unbounded memory growth on
long-running processes); getHighlights also uses union regexes
- bg-shell/process-manager: addOutputLine increments stdoutLineCount/
stderrLineCount in O(1) as lines arrive; getInfo uses tracked counters
instead of two O(n) .filter() passes over the output buffer
- gsd/diff-context: replace execFileSync with async execFile wrapper;
getRecentlyChangedFiles and getChangedFilesWithContext now run all
independent git queries concurrently via Promise.all (3-5 serial
subprocess spawns -> 1 parallel batch)
- gsd/workspace-index: per-slice indexing now runs concurrently via
Promise.all within each milestone; add IndexWorkspaceOptions with
validate flag (default false) — validatePlanBoundary/validateCompleteBoundary
skipped by default since they do expensive content analysis and are only
needed for explicit doctor/audit flows; getSuggestedNextCommands passes
validate:true as the sole consumer of validationIssues
Extensions run from ~/.gsd/agent/extensions/gsd/ at runtime, not from the
package install directory. The previous code traversed 4 levels up from
import.meta.url to find package.json, which resolves to ~/package.json at
runtime — wrong on every system.
The loader already sets process.env.GSD_VERSION at startup, which is how
every other extension reads the version. Use that instead.
ExtensionContext in the published package does not have getActiveTools —
it lives on ExtensionAPI (pi). The local source has it on both but CI
typechecks against the installed package, which failed with:
Property 'getActiveTools' does not exist on type 'ExtensionCommandContext'
guided-discuss-milestone.md was a single-paragraph stub — the agent had
no interview protocol, no check-in round, no depth verification, and no
host-conditional behaviour. On Copilot this meant every clarification
burned a separate request with no structure.
Changes:
- guided-discuss-milestone.md: full interview protocol matching
guided-discuss-slice structure:
- mandatory investigation pass before first round
- 1–3 questions per round
- check-in after each round (wrap up vs keep going)
- depth verification checklist before wrap-up
- host-conditional: uses ask_user_questions when available (pi),
falls back to plain text when not (Copilot, Cursor, Windsurf)
- depth_verification question ID convention preserved for the
write-gate in index.ts
- guided-flow.ts: all 5 loadPrompt('guided-discuss-milestone') call
sites now pass structuredQuestionsAvailable by checking
ctx.getActiveTools().includes('ask_user_questions') at dispatch time.
Returns 'true'/'false' string so the prompt can branch conditionally.
Four-part fix for the failure chain reported in #739:
1. **Dispatch guard** (auto-dispatch.ts): refuse to dispatch execute-task
when T{tid}-PLAN.md is missing on disk. Emits a stop action with a
clear error message instead of sending the agent in blind with a
missing plan, which was the proximate cause of the runaway session
and eventual EPIPE crash.
2. **verifyExpectedArtifact for plan-slice** (auto-recovery.ts): after
verifying S{sid}-PLAN.md exists, also check that every task listed in
the plan has a corresponding T{tid}-PLAN.md. A plan-slice that wrote
the slice plan but omitted task plans was previously considered
complete, allowing the dispatch guard above to be bypassed on
idempotency replay.
3. **EPIPE guard** (index.ts): register an uncaughtException handler at
extension load time that catches EPIPE (broken stdio pipe) and exits
cleanly instead of crashing with an unhandled exception. The crash in
#739 was triggered by process.stderr.write() calls to a closed pipe
during LSP diagnostics in the execute-task session.
4. **Prompt hardening** (prompts/research-slice.md): explicitly note that
the research template is already inlined in the prompt and must not be
read from disk. The agent in #739 hallucinated a read of
templates/SLICE-RESEARCH.md (ENOENT), causing the subagent to abort,
which left no S03-RESEARCH.md and poisoned the downstream plan-slice.
The bash tool waits for stdout/stderr file descriptors to close. When the
LLM runs 'python -m http.server 8080 &', the backgrounded process inherits
stdout and keeps it open — the bash call hangs indefinitely.
The bg_shell tool exists for exactly this purpose (detached process groups,
readiness detection, lifecycle management). The system prompt already said
to use bg_shell for servers but didn't explicitly warn against bash with &.
Added:
- Explicit anti-pattern: 'Never use bash with & to background a process'
- Expanded background processes section explaining why & hangs
- Both reference bg_shell start as the correct alternative
