toga-ai 1.0.479 → 1.0.481

package/knowledge/INDEX.md

@@ -39,6 +39,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **togatech** (TOGA Technology Website) — 4 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
 - **websocket** (WebSocket Server) — 2 doc(s) → [standalone/apps/websocket/INDEX.md](standalone/apps/websocket/INDEX.md)
 - **forward** (Forwarder) — 3 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
+- **claude** (Claude Harness) — 2 doc(s) → [standalone/apps/claude/INDEX.md](standalone/apps/claude/INDEX.md)
 
 ## Clients
 

package/knowledge/registry.json

@@ -184,7 +184,9 @@
     "project": "TOGa Commerce",
     "framework": "2.0",
     "role": "app",
-    "dependsOn": ["api2"]
+    "dependsOn": [
+      "api2"
+    ]
   },
   {
     "repo": "toga",
@@ -227,5 +229,12 @@
       "api2",
       "worker2"
     ]
+  },
+  {
+    "repo": "claude",
+    "project": "Claude Harness",
+    "framework": "standalone",
+    "role": "app",
+    "dependsOn": []
   }
 ]

package/knowledge/standalone/apps/claude/INDEX.md

@@ -0,0 +1,6 @@
+# claude (Claude Harness) — standalone knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [Harness Distribution — How a knowledge.js Fix Reaches Teammates](workflows/harness-distribution.md) | There are **two copies** of `knowledge.js` on a developer's machine, and the skills use only one of them. | claude/scripts/install.js, claude/knowledge.js |
+| [Knowledge Base Publish / Push Pipeline](workflows/knowledge-publish-pipeline.md) | How `/capture` and `/session-save` get knowledge docs from your working tree into `agilantsolutions/claude` on `_main`. | claude/knowledge.js |

package/knowledge/standalone/apps/claude/workflows/harness-distribution.md

@@ -0,0 +1,57 @@
+---
+title: Harness Distribution — How a knowledge.js Fix Reaches Teammates
+framework: "standalone"
+repo: claude
+project: Claude Harness
+client: shared
+type: workflow
+status: active
+updated: 2026-07-30
+owners: ["jcardinal"]
+files:
+  - claude/scripts/install.js
+  - claude/knowledge.js
+related:
+  - standalone/apps/claude/workflows/knowledge-publish-pipeline.md
+---
+
+## Summary
+There are **two copies** of `knowledge.js` on a developer's machine, and the skills use only
+one of them. Publishing a new npm version does **not** fix a teammate's `/capture` — the git
+clone is what has to be updated. `npx toga-ai` is the mechanism that does it.
+
+## How it works
+- `/capture`, `/kickoff`, and `/session-save` all invoke
+  `node "<TEAM_REPO>/knowledge.js"` — that is the **git clone's** copy at
+  `~/toga-tech/knowledge.js`.
+- The npm bundle installs a *separate* copy into the project's `.claude/knowledge.js`. The
+  skills do not run it, so a new published npm version alone changes nothing about captures.
+- `npx toga-ai` runs `tryGitPull()` (`scripts/install.js`, ~lines 182-210, called at ~line
+  548), which does `git pull --ff-only` inside `~/toga-tech`. **That pull is what actually
+  delivers a fixed `knowledge.js`.**
+- Equivalent manual route: `git -C ~/toga-tech pull`.
+
+Verify a teammate has a given fix:
+
+```
+git -C ~/toga-tech log --oneline -1 knowledge.js
+```
+
+For the 2026-07-30 publish/push fix, that must show `47fbdc4` or newer.
+
+## Gotchas / known issues
+- **`npx toga-ai` can silently fail to update the knowledge repo** (open issue, not yet
+  fixed). On a non-zero `git pull --ff-only` exit, `tryGitPull()` returns
+  `{ pulled: false, newDocs: 0, message: null }` — the git stderr is discarded and **nothing
+  is printed to the developer**. A teammate whose pull is refused (e.g. local edits to a
+  tracked file that the incoming commits also touch — `.claude/settings.json` is the usual
+  culprit) will believe they are up to date while still running old tooling.
+  Suggested fix, not applied: surface the git stderr in the `pulled: false` path so a refused
+  pull is visible. Same defect class as the swallowed-stderr bug in the publish pipeline.
+- Until that is fixed, if a harness fix "didn't take", check the pull manually rather than
+  trusting `npx toga-ai`'s output.
+
+## Change history
+- 2026-07-30 — Documented that the skills run the git clone's `knowledge.js` (not the npm
+  bundle copy), so `npx toga-ai` / `git -C ~/toga-tech pull` is required to distribute a
+  harness fix; recorded the silent `tryGitPull()` failure as a known issue. (jcardinal)

package/knowledge/standalone/apps/claude/workflows/knowledge-publish-pipeline.md

@@ -0,0 +1,72 @@
+---
+title: Knowledge Base Publish / Push Pipeline
+framework: "standalone"
+repo: claude
+project: Claude Harness
+client: shared
+type: workflow
+status: active
+updated: 2026-07-30
+owners: ["jcardinal"]
+files:
+  - claude/knowledge.js
+related:
+  - standalone/apps/claude/workflows/harness-distribution.md
+---
+
+## Summary
+How `/capture` and `/session-save` get knowledge docs from your working tree into
+`agilantsolutions/claude` on `_main`. Both go through `knowledge.js` — `cmdPublish()` for
+`/capture`, `pushStaged()` for `/session-save`. Both run the same three-step git sequence,
+and both had the same defect until 2026-07-30 (`47fbdc4`): they reported `PUSH_FAILED` on
+every run while a manual `git push` always worked.
+
+## How it works
+The publish sequence, run inside the team repo clone (`~/toga-tech`):
+
+1. `node knowledge.js validate` — aborts the publish on any `ERROR:` line.
+2. `git add` the touched paths under `knowledge/` and commit.
+3. `git fetch origin <branch>`
+4. `git rebase --autostash origin/<branch>`
+5. `git push origin HEAD:<branch>`
+
+Steps 3–5 are wrapped in a 3-attempt retry with a 2s/4s backoff between attempts
+(`sleepSync()`, implemented with `Atomics.wait`). On final failure the tool prints both the
+manual-push command **and** the underlying git error:
+
+```
+PUBLISH: PUSH_FAILED after 3 attempts — run manually: git -C "<TEAM>" push origin HEAD:_main
+PUBLISH: last git error — <git stderr, first 5 lines>
+```
+
+`/session-save` prints the same pair under a `SESSION:` prefix.
+
+Direct commits to `_main` in this repo are intentional and are the documented exception to
+the team's branch-protection rule. Force-pushing is never automatic here either.
+
+## Gotchas / known issues
+- **`git rebase` refuses to run while ANY tracked file has unstaged changes** — even a file
+  with nothing to do with `knowledge/`. It exits with
+  `error: cannot rebase: You have unstaged changes.` That means the rebase failed *before*
+  the push was ever attempted, which is why the manual `git push` always succeeded (push
+  does not require a clean working tree). `--autostash` is therefore **required, not a
+  nicety**: it stashes the unrelated edits, rebases, and restores them. Do not remove it.
+- **This was never a CI race.** The retry loop's original comment claimed it was retrying a
+  "CI version-bump race". That diagnosis was wrong, and three instant retries just repeated
+  the same deterministic failure three times.
+- **`.claude/settings.json` is tracked in this repo and is edited by the harness itself**, so
+  local drift there is expected and recurring. It was the dirty file that made the failure
+  100% reproducible on at least one machine. `--autostash` makes publish tolerate it, but the
+  drift still wants a periodic `git diff .claude/settings.json` decision — commit it or revert
+  it. It is also the file most likely to make `npx toga-ai`'s `git pull --ff-only` refuse (see
+  the harness distribution doc).
+- **A `catch` that discards `stderr` disguises a deterministic bug as a flaky one.** This bug
+  went undiagnosed for months purely because `catch (e)` threw git's stderr away while git was
+  naming the exact cause on every single run. Any retry wrapper around a shell command in this
+  repo must surface `e.stderr || e.stdout` on final failure.
+
+## Change history
+- 2026-07-30 — Fixed permanent `PUSH_FAILED`: `git rebase` → `git rebase --autostash`, surface
+  git stderr as a `last git error` line, and add 2s/4s backoff (`sleepSync()`) between retries.
+  Applied identically in `cmdPublish()` and `pushStaged()`, which had the same defect
+  (`47fbdc4`). (jcardinal)

package/knowledge.js

@@ -48,6 +48,17 @@ function fail(msg) {
     process.exitCode = 1;
 }
 
+/* Blocking sleep, for backing off between push retries. This script is a
+ * short-lived synchronous CLI, so there is no event loop to yield to and an
+ * async sleep would mean threading promises through every git call. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/* stderr of the last failed push attempt, so reportSession() can say WHY
+ * instead of only that it failed. */
+let lastPushError = '';
+
 function parseArgs(argv) {
     const out = {};
     for (const arg of argv) {
@@ -433,15 +444,23 @@ function cmdPublish(args) {
     const msg = String(args.msg || 'knowledge: capture session updates').replace(/["\\]/g, "'").slice(0, 200);
     run(`git commit -m "${msg}"`);
 
-    // 6. rebase-before-push, retrying the CI version-bump race up to 3x
+    // 6. rebase-before-push, retrying the CI version-bump race up to 3x.
+    //    --autostash is REQUIRED, not a nicety: plain `git rebase` aborts with
+    //    "cannot rebase: You have unstaged changes" if ANY tracked file is dirty,
+    //    even one unrelated to knowledge/ (.claude/settings.json is the usual
+    //    culprit — the harness edits it). That failure is not a conflict and not a
+    //    race, so it fails identically on all 3 attempts and every capture ends in
+    //    a manual push. --autostash stashes the unrelated edits, rebases, restores.
+    let lastError = '';
     for (let attempt = 1; attempt <= 3; attempt++) {
         try {
             run('git fetch origin');
-            run(`git rebase origin/${branch}`);
+            run(`git rebase --autostash origin/${branch}`);
             run(`git push origin HEAD:${branch}`);
             console.log(`PUBLISH: PUSHED to ${branch} — CI publishes a new npm version; teammates get it on \`npx toga-ai\``);
             return;
         } catch (e) {
+            lastError = String((e && (e.stderr || e.stdout)) || (e && e.message) || '').trim();
             let status = '';
             try { status = run('git status --porcelain'); } catch { /* ignore */ }
             if (/^(UU|AA|DD|AU|UA|DU|UD) /m.test(status)) {
@@ -449,10 +468,15 @@ function cmdPublish(args) {
                 console.log(`PUBLISH: CONFLICT — rebase onto origin/${branch} hit a real conflict; resolve manually, then re-run publish`);
                 process.exitCode = 1; return;
             }
-            // else: almost certainly a fresh CI bump (non-fast-forward) — loop and retry
+            // else: most likely a fresh CI bump (non-fast-forward). Back off before
+            // retrying — an instant retry loses the same race three times over.
+            if (attempt < 3) sleepSync(2000 * attempt);
         }
     }
+    // Always surface WHY. Swallowing stderr here is what disguised the dirty-tree
+    // bug above as a flaky CI race for months.
     console.log(`PUBLISH: PUSH_FAILED after 3 attempts — run manually: git -C "${TEAM}" push origin HEAD:${branch}`);
+    if (lastError) console.log('PUBLISH: last git error — ' + lastError.split('\n').slice(0, 5).join(' | '));
     process.exitCode = 1;
 }
 
@@ -766,20 +790,25 @@ function pushStaged(opts) {
     }
     const msg = String((opts && opts.msg) || 'sessions: update').replace(/["\\]/g, "'").slice(0, 200);
     gitRun(`git commit -m "${msg}"`);
+    // --autostash is REQUIRED: plain `git rebase` refuses to run while ANY tracked
+    // file is dirty, even one unrelated to what we staged, which fails identically
+    // on every attempt and forces a manual push. See cmdPublish() for the detail.
     for (let attempt = 1; attempt <= 3; attempt++) {
         try {
             gitRun('git fetch origin');
-            gitRun(`git rebase origin/${branch}`);
+            gitRun(`git rebase --autostash origin/${branch}`);
             gitRun(`git push origin HEAD:${branch}`);
             return 'PUSHED';
         } catch (e) {
+            lastPushError = String((e && (e.stderr || e.stdout)) || (e && e.message) || '').trim();
             let status = '';
             try { status = gitRun('git status --porcelain'); } catch { /* ignore */ }
             if (/^(UU|AA|DD|AU|UA|DU|UD) /m.test(status)) {
                 try { gitRun('git rebase --abort'); } catch { /* ignore */ }
                 return 'CONFLICT';
             }
-            // else: almost certainly a fresh CI bump (non-fast-forward) — retry
+            // else: most likely a fresh CI bump (non-fast-forward) — back off, retry
+            if (attempt < 3) sleepSync(2000 * attempt);
         }
     }
     return 'PUSH_FAILED';
@@ -792,7 +821,9 @@ function reportSession(status, branch) {
     if (status === 'NO_CHANGES') { console.log('SESSION: NO_CHANGES — nothing new to push'); return; }
     if (status === 'CONFLICT') { console.log(`SESSION: CONFLICT — rebase onto origin/${br} hit a real conflict; resolve manually, then retry`); process.exitCode = 1; return; }
     if (status && status.startsWith('ABORT_OUTSIDE')) { console.log('SESSION: ABORT_OUTSIDE_SESSIONS — refusing to commit non-session files: ' + status.slice('ABORT_OUTSIDE:'.length)); process.exitCode = 1; return; }
-    console.log(`SESSION: PUSH_FAILED after 3 attempts — run manually: git -C "${__dirname}" push origin HEAD:${br}`); process.exitCode = 1;
+    console.log(`SESSION: PUSH_FAILED after 3 attempts — run manually: git -C "${__dirname}" push origin HEAD:${br}`);
+    if (lastPushError) console.log('SESSION: last git error — ' + lastPushError.split('\n').slice(0, 5).join(' | '));
+    process.exitCode = 1;
 }
 
 function fetchQuiet() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.479",
+  "version": "1.0.481",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",