CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-05-30 23:09:32 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
64f9aafa1efd36b179c130c1ed8219403e5afda1
gstack/docs/designs/FIX_1671_PROFILE_MIGRATION.md
T
Garry Tan 64f9aafa1e v1.44.1.0 fix wave: post-windhoek paper-cut — 9 community PRs in one bundle (#1682) 
* fix(office-hours): #1671 — session writer was writing to the legacy file

User-visible symptom: returning /office-hours users get the same closing
pitch every visit, no matter how many times they've run the skill. The
welcome_back tier (which exists specifically to skip the pitch for
returning users) was unreachable. Live since 2026-04-18 / v1.0.0.0 on
every fresh-$HOME user.

Root cause: the v1.0.0.0 migration moved the read path to
~/.gstack/developer-profile.json but left the writer in
office-hours/SKILL.md.tmpl writing to the legacy
~/.gstack/builder-profile.jsonl. Reader and writer disagreed on storage,
so SESSION_COUNT never incremented and /office-hours always treated the
user as a first-timer.

Fix:
- bin/gstack-developer-profile: new --log-session subcommand that
  read-modify-writes developer-profile.json's sessions[] array (atomic
  mktemp+mv, signals/resources/topics aggregation, gbrain-enqueue mirror
  of gstack-timeline-log:40). Naming matches the gstack-*-log family verb.
- bin/gstack-developer-profile: do_read filters mode:"resources" entries
  when picking LAST_PROJECT/LAST_ASSIGNMENT/LAST_DESIGN_TITLE so the Phase
  6 resources auto-append doesn't clobber real-session state. Latent bug
  that was masked by the broken writer; activated by the fix.
- office-hours/SKILL.md.tmpl: lines 490 + 893 swap echo >> for --log-session.
- test/gstack-developer-profile.test.ts: +8 tests covering --log-session
  contract (regression, aggregation, dedup, validation, ts handling) plus
  the mode-filter regression. All 8 fail on main, all 8 pass with this fix.
- test/static-no-legacy-writes.test.ts: new static-grep invariant walking
  every skill dir to prevent future regressions onto the legacy file.

Affected users: stranded builder-profile.jsonl entries are not recovered
automatically by this PR. On their next /office-hours run, the first new
session lands in welcome_back; past data stays in the legacy file (still
readable by other tools during deprecation). Most pre-existing users have
only a handful of stranded sessions.

See docs/designs/FIX_1671_PROFILE_MIGRATION.md for scope decisions
(RC2/RC3 follow-ups, what was intentionally left out, and why).

Issue: #1671

* test(office-hours): refine #1671 invariant regex comment for literal-path scope

Clarifies that the WRITE_PATTERN regex catches literal-path writes only;
variable-indirected writes (FILE=...; echo >> "$FILE") are not detected.
The SKILL.md.tmpl assertions in the same suite pin the exact #1671
regression class directly; this regex is a backstop, not a flow analyzer.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(timeline): pass read filters as data

* feat(next-version): support monorepo VERSION paths via --version-path + .gstack/version-path

The workspace-aware ship queue hardcoded the VERSION file at the repo root.
In monorepos where versioning is subproject-scoped (one app inside a larger
repo), every PR's VERSION lookup 404s, the queue silently empties, and
parallel /ship sessions all bump from "current main + 1" — producing a
cascade of slot collisions.

Repro: tinas-second-brain repo. Root VERSION is absent; the real VERSION
lives at "Tinas Second Brain/health-tracker/VERSION". In one day, four
sequential collisions: 0.4.0.1 -> 0.5.0.0 -> 0.5.0.1 -> 0.5.0.2 -> 0.5.0.3.

Fix: add a --version-path flag and a repo-local .gstack/version-path
config file. Resolution priority: CLI flag > .gstack/version-path > "VERSION".
The resolved path threads through all four call sites — git show
origin/<base>:<path>, the GitHub Contents API, the GitLab files API, and
the local sibling-worktree scan — and shows up in the JSON output as
version_path so /ship and operators can see what got picked.

The previous warning "could not fetch VERSION (fork or private)" was
misleading whenever the real cause was wrong path. The new wording names
the path that 404'd and hints at the two knobs.

Backward-compatible: no flag, no config, no change in behavior.

Tests: 6 unit tests for resolveVersionPath (priority, parsing, blank /
missing / empty edge cases) + a second integration smoke that drives
--version-path end-to-end and asserts it surfaces in JSON output.

* fix(investigate): support standalone freeze hook path

* fix(browse): clarify localhost bind failures

* fix(migration): defer v1.40.0.0 done-marker until every repair succeeds (#1581)

The v1.40.0.0 migration unconditionally `touch`ed its done-marker, even
when the jq-gated `.brain-privacy-map.json` patch was skipped because jq
was missing on the user's machine. On subsequent runs, the script
short-circuited on the marker so the privacy-map repair never landed.
Federation sync then silently dropped `/plan-eng-review` test plans.

Track every failure mode via a single `incomplete` flag: jq missing,
malformed JSON, jq mutation failure, tempfile creation failure, `mv`
failure, allowlist append failure, gitattributes append failure. The
marker is written only when `incomplete=0`, so the migration runner
retries on the next /gstack-upgrade once the prerequisites are met.

* test(migration): unit tests for v1.40.0.0 deferred done-marker fix (#1581)

8 cases pinning the fix:

- Case 1 (happy path): jq present, fresh privacy-map → all three files
  patched, marker written.
- Case 2 (regression for #1581): jq missing, privacy-map present →
  marker must NOT be written. Fails against the buggy script, passes
  against the fix.
- Case 3 (recovery): jq missing, then jq restored → patch lands on
  second run.
- Case 4 (idempotency): privacy-map already has correct entry →
  no mutation, marker written.
- Case 5 (fresh-init): privacy-map file absent → allowlist + gitattrs
  patched, marker written.
- Case 6 (malformed JSON): broken privacy-map JSON → no marker, no
  mutation.
- Case 7 (jq mutation failure): fake jq returning 1 → no marker,
  tempfile cleaned up.
- Case 8 (allowlist append failure): read-only allowlist → no marker.

Tests use spawnSync('bash', [MIGRATION], …) with isolated tmpHomes.
"jq missing" sets PATH to a curated dir of symlinks to standard utils,
omitting jq; "jq mutation fails" uses an `exit 1` shim. Avoids
blanket-clearing PATH (which would hide bash/grep/etc).

* fix(brain-sync): make artifact sync work on Windows (discover-new + drain)

Automatic artifact sync was fully non-functional on Windows (Git Bash):
--discover-new enqueued nothing and the --once drain staged nothing, so
artifacts_sync_mode looked active but no artifacts ever reached the repo.
Three independent Windows-only causes in bin/gstack-brain-sync:

1. discover-new matched os.path.relpath (backslash separators on Windows)
   against the forward-slash allowlist globs, so no nested file ever matched.
   Normalized the relpath to "/".
2. discover-new enqueued via subprocess.run([gstack-brain-enqueue, rel]), but
   Windows Python cannot exec a bash-shebang script, so nothing was enqueued
   even once matched. Now appends to the queue in-process.
3. compute_paths_to_stage ends in print(p); Windows Python emits CRLF, the
   bash `read -r` keeps the trailing CR, and `git add -- "path<CR>"` matches
   nothing under `2>/dev/null || true`. Now strips the CR before staging.

The in-process enqueue mirrors gstack-brain-enqueue's contract: one atomic
O_APPEND write per record (each line < PIPE_BUF) so a parallel writer-shim
append can't interleave mid-record, and the discover cursor advances only
after the write succeeds, so a failed write retries instead of silently
recording the file as synced. Skip-list entries are separator-normalized on
both the discover and drain (compute_paths_to_stage) sides, so a backslash
.brain-skip.txt entry can't be honored at discovery yet bypassed at commit.

Adds test/brain-sync-windows-paths.test.ts (static invariants -- behavioral
spawn tests cannot run on the Windows lane, since Node/Bun cannot exec the
bin/ shebang scripts there) and wires it into windows-free-tests.yml.
Verified red->green and end-to-end on Windows 11 / Git Bash; macOS/Linux
behavior unchanged (os.sep is already "/", no CRLF, compute path logic
unchanged besides the shared skip normalization).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix: detect bun.lock (Bun v1.2+ text lockfile) in diff-scope CONFIG

gstack-diff-scope only matched the legacy binary lockfile `bun.lockb`
but not the newer text-based `bun.lock` introduced in Bun v1.2+.
Projects using current Bun versions were silently missing the
SCOPE_CONFIG signal when only the lockfile changed.

🤖 Generated with [Qoder][https://qoder.com]

* fix(ios-qa): resolve CoreDevice tunnel via devicectl + keep tunnel alive

The daemon's tunnel bootstrap used `dns.resolve6` to look up
`<device>.coredevice.local`, which fails with ESERVFAIL on macOS 26.x
(Darwin 25.x) because Node's resolve6 path goes through libresolv and
does NOT consult mDNSResponder. `dns.lookup` (getaddrinfo) does.

Even when resolution works, CoreDevice in Xcode 26 only holds the
USB tunnel up while a devicectl command is in-flight, so the IPv6 ULA
becomes unroutable within ~10-15s of idle and subsequent proxy
requests time out.

Two-part fix:

  1. Resolution order is now (a) `xcrun devicectl device info details
     --json-output` to read `result.connectionProperties.tunnelIPAddress`
     directly, (b) mDNS via `dns.lookup`, (c) legacy `dns.resolve6` as
     a last-ditch fallback.
  2. After a successful bootstrap the daemon spawns a periodic
     `devicectl device info details` (~5s) to keep the tunnel session
     alive. Cleaned up on SIGINT/SIGTERM/exit.

Adds tests for `getDeviceTunnelIPv6FromDevicectl`, the
`resolveTunnelIPv6` fallback chain, and `startTunnelKeepalive`.
Existing bootstrap tests updated to include the new
`device info details` spawn step.

Tested against: iPhone 12 Pro on iOS 26.x via Mac Mini M-series
running macOS Sequoia 15.x / Darwin 25.3.0.

* chore(release): v1.44.1.0 — 9-PR community fix wave (post-windhoek paper-cut)

Bump VERSION + CHANGELOG entry. Wave covers /office-hours session
counter, iOS QA macOS 26 tunnels, Windows brain-sync, browse server
bind diagnostics, monorepo VERSION layouts, /investigate freeze hook
on standalone installs, gstack-timeline-read quote injection,
v1.40.0.0 migration on jq-less machines, bun.lock detection.

9 community PRs: #1676 #1635 #1627 #1648 #1664 #1589 #1672 #1649 #1673
9 contributors credited: @pryow @jbetala7 @cfeddersen @Gujiassh
@spacegeologist @stedfn @daveowenatl @hiSandog @sternryan
4 issues closed: #1671 #1677 #1634 #1647 #1581

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Rook <rook@robomovers.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Jayesh Betala <jayesh.betala7@gmail.com>
Co-authored-by: Christoph <astaran@herr-der-ringe-film.de>
Co-authored-by: gujishh <baiaoshh@163.com>
Co-authored-by: zhengzuo0-ai <zheng.zuo0@gmail.com>
Co-authored-by: Stefan Neamtu <stefan.neamtu@nearone.org>
Co-authored-by: Dave Owen <daveowen66@gmail.com>
Co-authored-by: 陈家名 <chenjiaming@kezaihui.com>
Co-authored-by: Ryan Stern <206953196+sternryan@users.noreply.github.com>
2026-05-25 10:57:15 -07:00

6.3 KiB
Raw Blame History

Fix #1671: /office-hours always reports SESSION_COUNT: 0

Status: SHIPPED Branch: fix-1671-profile-migration Date: 2026-05-23 Issue: https://github.com/garrytan/gstack/issues/1671 Original PR that introduced the bug: garrytan/gstack#1039 / commit 0a803f9 / v1.0.0.0 / 2026-04-18

The problem

/office-hours reports SESSION_COUNT: 0 and TIER: introduction on every invocation, even for users who have run the skill many times. The welcome_back tier (bin/gstack-developer-profile:165-169) that exists to skip the closing pitch for returning users is unreachable. Live ~5 weeks on every fresh-$HOME user since v1.0.0.0.

Root cause

The v1.0.0.0 migration moved the read path to ~/.gstack/developer-profile.json but left the writer in office-hours/SKILL.md.tmpl writing to the legacy ~/.gstack/builder-profile.jsonl. The ensure_profile stub created on first read has sessions: []; subsequent writes go to a file the reader never re-reads. Reader and writer disagree on storage.

Full root-cause analysis (including RC2/RC3 follow-ups): https://github.com/garrytan/gstack/issues/1671

The fix

Make the writer use the same file the reader does.

Changes

  1. bin/gstack-developer-profile — add --log-session '<json>' subcommand:

    • Validates required fields (date, mode), silent-skip on invalid input (matches bin/gstack-timeline-log:22-26).
    • Reads existing developer-profile.json via bun -e.
    • Appends entry to sessions[]. Updates signals_accumulated (per-signal-string increment, same as do_migrate:67-69), unions resources_shown and topics.
    • Atomic mktemp+mv write (matches existing pattern at line 54).
    • Calls gstack-brain-enqueue "developer-profile.json" after write, mirroring bin/gstack-timeline-log:40.

  2. bin/gstack-developer-profile:do_read — filter mode:"resources" entries when picking LAST_PROJECT / LAST_ASSIGNMENT / LAST_DESIGN_TITLE / CROSS_PROJECT / DESIGN_*. The Phase 6 resources auto-append happens after the real session in the same /office-hours invocation; without the filter, that resources entry clobbers real-session state for the user's next session. Latent bug that was masked by the broken writer; activated by the fix.

  3. office-hours/SKILL.md.tmpl — swap writers at lines 490 and 893:

    • From: echo '{...}' >> "$GSTACK_STATE_ROOT/builder-profile.jsonl"
    • To: ~/.claude/skills/gstack/bin/gstack-developer-profile --log-session '{...}' 2>/dev/null || true
    • Run bun run gen:skill-docs to regenerate office-hours/SKILL.md.

What's NOT in the fix (intentionally)

  • No new binary. The owner binary for developer-profile.json is gstack-developer-profile; the writer belongs there as a subcommand. --log-session joins the binary's existing --migrate / --derive write-side subcommand boundary, not the gstack-*-log event-writer family. Verb name still matches gstack-*-log.
  • No mkdir-locks. Concurrent /office-hours calls have a read-modify-write race on developer-profile.json. The codebase accepts the same race in gstack-config (r-m-w on YAML, no lock). Not introduced by this fix; out of scope.
  • No schema bump. Schema stays at schema_version: 1. The fix doesn't change the schema, just makes the writer use it.
  • No auto-reconcile for affected users. Existing users with stranded builder-profile.jsonl entries don't get their past history auto-merged into developer-profile.json. On their next /office-hours run, the first new session lands in welcome_back; past data stays in the legacy file (still readable by other tools during deprecation). Most affected users have only a handful of stranded sessions so the loss is mostly aesthetic. Dropped the one-release-only reconcile pathway as net noise — Garry's "right-sized diff" voice.
  • No autoplan timeline rollup (RC2). Separate concern, separate PR.
  • No project-scope opt-in (RC3). Separate concern, separate PR.
  • No gbrain glob change. The office-hours manifest still globs ~/.gstack/builder-profile.jsonl for context; once new writes stop landing there, the snapshot goes cold. Update in a follow-up if it becomes a UX issue.

Tests (all gate-tier, free, deterministic)

  1. Regression test in test/gstack-developer-profile.test.ts:

    • Fresh $HOME.
    • Run /office-hours preamble: gstack-developer-profile creates empty stub.
    • Call --log-session with a startup-mode JSON.
    • Run --read again. Assert SESSION_COUNT: 1, TIER: welcome_back.
    • Fails on current main (subcommand doesn't exist). Passes with fix.

  2. do_read mode filter test: after recording a startup session followed by a resources entry, --read returns LAST_PROJECT / LAST_ASSIGNMENT / LAST_DESIGN_TITLE from the real session, not from the resources entry. RESOURCES_SHOWN still aggregates correctly.

  3. Validation + aggregation tests: --log-session silently skips invalid JSON / missing required fields, injects ts if missing, preserves user-set ts, correctly aggregates signals/resources/topics across multiple sessions.

  4. Static-grep invariant in test/static-no-legacy-writes.test.ts (new): walks every skill dir, asserts no production code path writes to builder-profile.jsonl except allowlisted readers (gstack-developer-profile, gstack-memory-ingest.ts, gstack-artifacts-init, doc files). Prevents future writers from regressing onto the legacy file.

Acceptance criteria

  • Second /office-hours invocation on a fresh $HOME returns TIER: welcome_back.
  • bun test passes on the touched files in isolation.
  • bun run gen:skill-docs produces clean diff matching the .tmpl edits.

Rollout

  • One commit. PATCH version bump per CHANGELOG style guide.
  • CHANGELOG entry written by /ship. User-facing voice: lead with what users experience now that they didn't before (welcome_back tier kicks in on second visit).

Follow-up TODOs

  • Deprecate builder-profile.jsonl entirely (writer + shim + memory-ingest type) after one release.
  • Fix RC2 (autoplan inlines sub-skills, bypassing their timeline-log preambles).
  • Add GSTACK_PROFILE_SCOPE opt-in for power users with multiple agent identities (RC3).
  • /plan-tune doesn't currently call --derive, so inferred/gap can drift (pre-existing, unrelated to #1671).
  • mode:"resources" entries inflate SESSION_COUNT under the existing tier aggregator (pre-existing, unrelated to #1671 root cause).
Reference in New Issue View Git Blame Copy Permalink