From bc64f5e21082deab992c256811f23def0bec5bf1 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Wed, 18 Nov 2026 02:34:52 +0800 Subject: [PATCH] /sync-gbrain reports failed pushes and imports instead of OK, and one bad queued path no longer blocks artifacts sync (#4455) /sync-gbrain now says when an artifacts push failed or memory pages failed to import, instead of printing OK and "pushed", and one malformed queued path (from a skill started where the project slug was empty) no longer stops artifacts sync for every project. Why: people trusted those rows and lost track of unsynced work; fixes #4445, #4418 and #4417. Nothing to do after upgrading: a stuck `projects//timeline.jsonl` record is dropped and reported on the next sync. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> Review-Finding: p1/red-team#1 reader=red-team Review-Finding: p1/red-team#2 reader=red-team Review-Finding: p1/specialist-batched#1 reader=testing Review-Finding: p1/specialist-batched#2 reader=testing Review-Finding: p1/specialist-batched#3 reader=testing --- bin/gstack-brain-enqueue | 13 ++ bin/gstack-brain-sync | 54 ++++++-- bin/gstack-gbrain-sync.ts | 127 +++++++++++++----- bin/gstack-memory-ingest.ts | 16 ++- changelog.d/sync-gbrain-reports-failures.md | 3 + docs/gbrain-sync-errors.md | 33 +++++ sync-gbrain/SKILL.md | 16 ++- sync-gbrain/SKILL.md.tmpl | 16 ++- test/brain-sync.test.ts | 66 +++++++++ ...gstack-gbrain-sync-transcript-mode.test.ts | 54 ++++++++ test/gstack-gbrain-sync.test.ts | 111 ++++++++++++++- 11 files changed, 451 insertions(+), 58 deletions(-) create mode 100644 changelog.d/sync-gbrain-reports-failures.md diff --git a/bin/gstack-brain-enqueue b/bin/gstack-brain-enqueue index b6706a042..98183abf3 100755 --- a/bin/gstack-brain-enqueue +++ b/bin/gstack-brain-enqueue @@ -15,6 +15,9 @@ # - ~/.gstack/.git doesn't exist (feature not initialized) # - matches a line in ~/.gstack/.brain-skip.txt # +# Refuses (exit 1, nothing queued) a with an empty, "." or ".." +# component, such as projects//timeline.jsonl from an empty project slug. +# # Env: # GSTACK_HOME — override ~/.gstack state directory (aligns with writers). # Tests use GSTACK_HOME=/tmp/test-$$ for isolation. @@ -32,6 +35,16 @@ set -uo pipefail FILE="${1:-}" [ -z "$FILE" ] && exit 0 +# A path with an empty, "." or ".." component (projects//timeline.jsonl from an +# empty project slug, #4445) names a file git stages under another spelling, +# and the drain refuses that batch. Refuse it here instead of spooling it. +case "/$FILE/" in + *//*|*/./*|*/../*) + echo "gstack-brain-enqueue: refusing malformed path '$FILE' (empty, '.' or '..' component; an empty project slug?); nothing queued" >&2 + exit 1 + ;; +esac + # Plan B1: an unattended session never spools for cross-machine sync, whatever # the inherited mode; every writer (timeline, decision, learnings, review log) # is covered here, at the one entrypoint, instead of per caller. diff --git a/bin/gstack-brain-sync b/bin/gstack-brain-sync index fd89a98d3..2c1c713e6 100755 --- a/bin/gstack-brain-sync +++ b/bin/gstack-brain-sync @@ -193,6 +193,23 @@ with open(path, "w") as f: PYEOF } +# Status for a drain that pushed nothing. While local commits are still not on +# origin, push_failed replaces ok and idle: writing those instead erased a +# failed push one run later, so a push that never recovered went silent +# (#4418). held and collision keep their code (their attention line names the +# files to fix) and carry the unpushed count in the message. +# $1 code, $2 message, $3 unpushed local commits. +write_drain_status() { + local unpushed="$3 local commit(s) are not pushed yet; the push retries at a skill start at most every 10 minutes (commits made outside gstack-brain-sync are never auto-pushed: push them with 'git -C $GSTACK_HOME push origin HEAD')" + if [ "${3:-0}" -eq 0 ]; then + write_status "$1" "$2" + elif [ "$1" = held ] || [ "$1" = collision ]; then + write_status "$1" "$2; $unpushed" + else + write_status "push_failed" "$unpushed; this drain: $2" + fi +} + # Read config; return 0 if sync active, 1 otherwise. sync_active() { if [ ! -d "$GSTACK_HOME/.git" ]; then @@ -464,8 +481,11 @@ for p in sorted(queue_paths): if p in skip_lines or any(m in skip_lines for m in members): classified["dropped"]["skipped"].append(p) continue - # Must be under GSTACK_HOME root. Reject absolute + reject ../ escape. - if p.startswith("/") or ".." in p.split("/"): + # Must be under GSTACK_HOME root and spelled the way git stages it: an + # absolute path, a ../ escape, or an empty or "." component (#4445: + # projects//timeline.jsonl from an empty slug, staged by git as + # projects/timeline.jsonl, made the index check refuse the whole batch). + if any(c in ("", ".", "..") for c in p.split("/")): classified["dropped"]["invalid"].append(p) continue # Must match at least one allowlist glob. @@ -677,7 +697,8 @@ finalize_queue() { # Fail-open by design (a failed finalize self-corrects next run: re-stage → # nothing-to-commit), but say so — a silent failure here would let the # subsequent "ok/idle" status claim a drain that did not happen. - python3 - "$QUEUE_DIR" "$snapshot_file" "$class_file" "$paths_file" "$GSTACK_HOME/.brain-sync-drops.json" <<'PYEOF' || echo "BRAIN_SYNC: warning: queue finalize failed — entries retained; next run re-drains" >&2 + local finalized=1 + python3 - "$QUEUE_DIR" "$snapshot_file" "$class_file" "$paths_file" "$GSTACK_HOME/.brain-sync-drops.json" <<'PYEOF' || { finalized=0; echo "BRAIN_SYNC: warning: queue finalize failed — entries retained; next run re-drains" >&2; } import json, os, sys, time spool_dir, snapshot_file, class_file, paths_file, drops_file = sys.argv[1:6] @@ -762,6 +783,16 @@ if dropped: json.dump({"ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "dropped": classified.get("dropped", {})}, f) PYEOF + [ "$finalized" = 1 ] || return 0 + # #4445: report malformed records once finalize has dropped them; an early + # exit before finalize keeps them queued and must not claim the drop. + local malformed + malformed=$(python3 -c 'import json, sys; print(len((json.load(open(sys.argv[1])).get("dropped") or {}).get("invalid") or []))' "$class_file" 2>/dev/null || echo 0) + case "$malformed" in ''|*[!0-9]*) malformed=0 ;; esac + if [ "$malformed" -gt 0 ]; then + ST_NOTE="$ST_NOTE; dropped $malformed queued record(s) with a malformed path (absolute, or an empty, '.' or '..' component), listed in $GSTACK_HOME/.brain-sync-drops.json" + echo "BRAIN_SYNC: dropped $malformed queued record(s) with a malformed path; see $GSTACK_HOME/.brain-sync-drops.json" >&2 + fi } # Human-readable classification counts for status messages. @@ -1316,14 +1347,9 @@ subcmd_once() { # the queue is empty.) The lock-release trap installed at acquisition # covers this exit. if ! spool_has_records && [ ! -s "$QUEUE" ] && [ ! -s "$QUEUE.migrating" ]; then - # Stranded local commits that this run did not push keep the status at - # push_failed: an "idle" here used to erase the failure one boundary later, - # so a push that never recovered went silent. - if [ "$det_total" -gt 0 ]; then - write_status "push_failed" "$det_total local commit(s) are not pushed yet; the push retries at a skill start at most every 10 minutes (commits made outside gstack-brain-sync are never auto-pushed: push them with git -C $GSTACK_HOME push origin HEAD)" - exit 0 - fi - if [ "$REMOVALS_PUSHED" = 1 ]; then write_status "ok" "queue empty"; else write_status "idle" "queue empty"; fi + local empty_code=idle + [ "$REMOVALS_PUSHED" = 1 ] && empty_code=ok + write_drain_status "$empty_code" "queue empty" "$det_total" exit 0 fi @@ -1362,7 +1388,7 @@ subcmd_once() { local summary idle_code=idle summary=$(queue_summary "$class_file") [ "$ST_CASE_HELD" -gt 0 ] && idle_code=collision - write_status "$idle_code" "no stageable changes${summary:+ ($summary)}" + write_drain_status "$idle_code" "no stageable changes${summary:+ ($summary)}" "$det_total" exit 0 fi local n_stageable @@ -1419,9 +1445,9 @@ subcmd_once() { if [ "$cached_rc" -eq 0 ]; then finalize_queue "$snapshot_file" "$class_file" "$paths_file" if [ "$ok_code" != "ok" ]; then - write_status "$ok_code" "nothing else to sync" + write_drain_status "$ok_code" "nothing else to sync" "$det_total" else - write_status "idle" "queue drained but no new changes to commit" + write_drain_status "idle" "queue drained but no new changes to commit" "$det_total" fi exit 0 fi diff --git a/bin/gstack-gbrain-sync.ts b/bin/gstack-gbrain-sync.ts index 4087df644..9b8113f21 100644 --- a/bin/gstack-gbrain-sync.ts +++ b/bin/gstack-gbrain-sync.ts @@ -29,10 +29,10 @@ * than building a gstack-side daemon. */ -import { existsSync, statSync, mkdirSync, writeFileSync, readFileSync, unlinkSync, renameSync, realpathSync, readdirSync, appendFileSync } from "fs"; +import { existsSync, statSync, mkdirSync, mkdtempSync, writeFileSync, readFileSync, rmSync, unlinkSync, renameSync, realpathSync, readdirSync, appendFileSync } from "fs"; import { join, dirname, basename, isAbsolute } from "path"; import { execSync, spawnSync } from "child_process"; -import { homedir, hostname } from "os"; +import { homedir, hostname, tmpdir } from "os"; import { createHash } from "crypto"; import "../lib/conductor-env-shim"; @@ -262,32 +262,88 @@ function isArtifactsSourceRow(r: { local_path?: string }, env?: NodeJS.ProcessEn } /** - * A5 (#2670): after a successful artifacts push, report what gbrain actually - * holds. A git push is not indexing; a maintained artifacts source with zero - * pages is the one provably broken state and fails the stage. + * A5 (#2670): after an artifacts drain, report what gbrain actually holds. A + * git push is not indexing; a maintained artifacts source with zero pages is + * the one provably broken state and fails the stage. `lead` says what the + * drain did. */ -export function brainSyncIndexVerdict(env: NodeJS.ProcessEnv = process.env): { ok: boolean; summary: string } { +export function brainSyncIndexVerdict( + env: NodeJS.ProcessEnv = process.env, + lead = "curated artifacts pushed to git", +): { ok: boolean; summary: string } { const raw = execGbrainJson(["sources", "list", "--json"], { baseEnv: env, timeout: 10_000 }); if (raw === null) { - return { ok: true, summary: "curated artifacts pushed to git; gbrain page count unavailable (gbrain sources list failed)" }; + return { ok: true, summary: `${lead}; gbrain page count unavailable (gbrain sources list failed)` }; } const explicit = env.GSTACK_BRAIN_SOURCE_ID; const row = parseSourcesList(raw).find((r) => (explicit ? r.id === explicit : isArtifactsSourceRow(r, env))); if (!row?.id) { - return { ok: true, summary: "curated artifacts pushed to git (no gbrain artifacts source on this machine, so indexing is not checked here)" }; + return { ok: true, summary: `${lead} (no gbrain artifacts source on this machine, so indexing is not checked here)` }; } if (typeof row.page_count !== "number") { - return { ok: true, summary: `curated artifacts pushed to git; gbrain source ${row.id} did not report a page count` }; + return { ok: true, summary: `${lead}; gbrain source ${row.id} did not report a page count` }; } if (row.page_count === 0) { return { ok: false, - summary: - `curated artifacts pushed to git, but gbrain source ${row.id} has 0 indexed pages. ` + - `Fix: gbrain sync --source ${row.id}, then re-run /sync-gbrain`, + summary: `${lead}, but gbrain source ${row.id} has 0 indexed pages. Fix: gbrain sync --source ${row.id}, then re-run /sync-gbrain`, }; } - return { ok: true, summary: `curated artifacts pushed; gbrain source ${row.id} has ${row.page_count} pages` }; + return { ok: true, summary: `${lead}; gbrain source ${row.id} has ${row.page_count} pages` }; +} + +/** + * The brain-sync row (#4418). `gstack-brain-sync --once` exits 0 when its push + * fails (the commit is kept and retried), so the row comes from the status the + * drain wrote, and only a drain whose status is ok says "pushed". `drain` is + * null when this run wrote no status (sync off, or another drain held the lock). + */ +export function brainSyncStageVerdict( + drain: { status?: unknown; message?: unknown } | null, + env: NodeJS.ProcessEnv = process.env, +): { ok: boolean; warn?: boolean; summary: string } { + if (!drain) return brainSyncIndexVerdict(env, "no artifacts drain ran (artifacts sync is off, or another sync held the lock), so nothing was pushed"); + const status = typeof drain.status === "string" ? drain.status : "unknown"; + const message = (typeof drain.message === "string" ? drain.message : "").slice(0, 400); + const detail = `${status}: ${message || "no message"}; details: gstack-brain-sync --status`; + if (status === "ok") return brainSyncIndexVerdict(env); + if (status === "idle") return brainSyncIndexVerdict(env, `nothing new to push (${message || "idle"})`); + if (status === "held" || status === "collision") { + const v = brainSyncIndexVerdict(env, `artifacts not all pushed (${detail})`); + return { ...v, warn: v.ok }; + } + return { ok: false, summary: `artifacts not pushed (${detail})` }; +} + +/** + * The memory row (#4417). gstack-memory-ingest exits 0 when single pages fail + * (they are retried next run), so the exit code alone printed OK with every + * page refused. The counts decide: a failed page makes the row WARN, and a run + * that imported nothing while pages failed is ERR. A source file that could not + * be parsed is never retried as an import, so it is a note, not a failure. + */ +export function memoryStageVerdict( + status: number | null, + stderr: string, + counts: { written?: unknown; failed?: unknown; parse_failed?: unknown } | null, +): { ok: boolean; warn?: boolean; summary: string } { + const memLines = stderr.split("\n").filter((l) => l.includes("[memory-ingest]")); + const errLine = memLines.find((l) => l.includes("[memory-ingest] ERR")); + const summary = (errLine || memLines.slice(-1)[0] || "ingest pass complete") + .replace(/^.*\[memory-ingest\]\s*/, "") + .replace(/^ERR:\s*/, ""); + if (status !== 0) { + return { ok: false, summary: `${summary}${status === null ? " (killed by signal / timeout)" : ` (exit ${status})`}` }; + } + const parseFailed = typeof counts?.parse_failed === "number" ? counts.parse_failed : 0; + const failed = Math.max(0, (typeof counts?.failed === "number" ? counts.failed : 0) - parseFailed); + const unparsed = parseFailed > 0 ? `; ${parseFailed} source file(s) could not be parsed and were skipped` : ""; + if (failed === 0) return { ok: true, summary: summary + unparsed }; + const written = typeof counts?.written === "number" ? counts.written : 0; + const first = memLines.find((l) => l.includes("[memory-ingest] FAILED ")); + const cause = first ? `; first: ${first.replace(/^.*\[memory-ingest\] FAILED\s*/, "").slice(0, 240)}` : ""; + const line = `${written} imported, ${failed} failed (retried next run; each failure: gstack-memory-ingest --incremental)${cause}${unparsed}`; + return written === 0 ? { ok: false, summary: line } : { ok: true, warn: true, summary: line }; } export interface MemorySourceSelection { @@ -1634,36 +1690,27 @@ function runMemoryIngest(args: CliArgs, previous: SyncState, consent: Transcript process.env.GSTACK_SYNC_MEMORY_TIMEOUT_MS, "GSTACK_SYNC_MEMORY_TIMEOUT_MS", ); + // D6: the child's [memory-ingest] stderr lines carry the summary and any + // system error; its counts (GSTACK_INGEST_RESULT_FILE) decide whether pages + // failed, since per-page failures exit 0 (#4417). + const resultFile = join(mkdtempSync(join(tmpdir(), "gstack-ingest-result-")), "result.json"); + childEnv.GSTACK_INGEST_RESULT_FILE = resultFile; const result = spawnSync(process.execPath, ingestArgs, { encoding: "utf-8", timeout: memoryTimeoutMs, env: childEnv, }); + let counts: { written?: unknown; failed?: unknown } | null = null; + try { + counts = JSON.parse(readFileSync(resultFile, "utf-8")); + } catch {} + rmSync(dirname(resultFile), { recursive: true, force: true }); - // D6: parse [memory-ingest] lines from the child's stderr. ERR-prefixed - // lines indicate a system-level failure (gbrain crashed or CLI missing) - // and the child exits non-zero. Per-file failures are summarized in the - // last non-ERR [memory-ingest] line but do NOT make the verdict ERR. - const stderrLines = (result.stderr || "").split("\n"); - const memLines = stderrLines.filter((l) => l.includes("[memory-ingest]")); - const errLine = memLines.find((l) => l.includes("[memory-ingest] ERR")); - const lastMemLine = memLines.slice(-1)[0]; - const rawSummary = errLine || lastMemLine || "ingest pass complete"; - // Strip the "[memory-ingest] " prefix and any leading "ERR: " for cleaner - // verdict output. The orchestrator's own formatStage will prefix with OK/ERR. - const summary = rawSummary - .replace(/^.*\[memory-ingest\]\s*/, "") - .replace(/^ERR:\s*/, ""); - - const ok = result.status === 0; return { name: "memory", ran: true, - ok, duration_ms: Date.now() - t0, - summary: ok - ? summary - : `${summary}${result.status === null ? " (killed by signal / timeout)" : ` (exit ${result.status})`}`, + ...memoryStageVerdict(result.status, result.stderr || "", counts), memory_sources: selected, transcript_consent: consentRecord, }; @@ -1708,12 +1755,24 @@ function runBrainSyncPush(args: CliArgs): StageResult { : ["ignore", "inherit", "inherit"]; spawnSync(discover.cmd, discover.argv, { stdio, timeout: 60 * 1000, shell: discover.shell }); + const statusPath = join(GSTACK_HOME, ".brain-sync-status.json"); + const statusStamp = () => (existsSync(statusPath) ? `${statSync(statusPath).mtimeMs}:${readFileSync(statusPath, "utf-8")}` : null); + const before = statusStamp(); const result = spawnSync(once.cmd, once.argv, { stdio, timeout: 60 * 1000, shell: once.shell }); if (result.status !== 0) { return { name: "brain-sync", ran: true, ok: false, duration_ms: Date.now() - t0, summary: `gstack-brain-sync exited ${result.status}` }; } - return { name: "brain-sync", ran: true, duration_ms: Date.now() - t0, ...brainSyncIndexVerdict() }; + let drain: { status?: unknown; message?: unknown } | null = null; + const after = statusStamp(); + if (after !== null && after !== before) { + try { + drain = JSON.parse(readFileSync(statusPath, "utf-8")); + } catch { + drain = { status: "unknown", message: `${statusPath} is unreadable` }; + } + } + return { name: "brain-sync", ran: true, duration_ms: Date.now() - t0, ...brainSyncStageVerdict(drain) }; } /** diff --git a/bin/gstack-memory-ingest.ts b/bin/gstack-memory-ingest.ts index 51a7963fb..924ccbb05 100644 --- a/bin/gstack-memory-ingest.ts +++ b/bin/gstack-memory-ingest.ts @@ -195,6 +195,8 @@ interface BulkResult { /** #2392: transcripts skipped because their remote's trust tier is `deny`. */ skipped_policy_deny: number; failed: number; + /** Source files that could not be parsed, counted in failed; not import failures. */ + parse_failed?: number; duration_ms: number; partial_pages: number; /** A1: pages gbrain refused or that were not found after import (retried next run). */ @@ -2134,6 +2136,7 @@ async function ingestPassScoped(args: CliArgs, state: IngestState, scope: Transc skipped_policy_readonly: prep.skippedPolicyReadonly, skipped_policy_deny: prep.skippedPolicyDeny, failed: prep.parseFailed + prep.prepared.length, + parse_failed: prep.parseFailed, duration_ms: Date.now() - t0, partial_pages: prep.partialPages, system_error: prep.policyError, @@ -2159,6 +2162,7 @@ async function ingestPassScoped(args: CliArgs, state: IngestState, scope: Transc skipped_policy_readonly: prep.skippedPolicyReadonly, skipped_policy_deny: prep.skippedPolicyDeny, failed: prep.parseFailed, + parse_failed: prep.parseFailed, duration_ms: Date.now() - t0, partial_pages: prep.partialPages, }; @@ -2180,6 +2184,7 @@ async function ingestPassScoped(args: CliArgs, state: IngestState, scope: Transc skipped_policy_readonly: prep.skippedPolicyReadonly, skipped_policy_deny: prep.skippedPolicyDeny, failed: prep.parseFailed, + parse_failed: prep.parseFailed, duration_ms: Date.now() - t0, partial_pages: prep.partialPages, }; @@ -2198,6 +2203,7 @@ async function ingestPassScoped(args: CliArgs, state: IngestState, scope: Transc skipped_policy_readonly: prep.skippedPolicyReadonly, skipped_policy_deny: prep.skippedPolicyDeny, failed: prep.parseFailed + prep.prepared.length, + parse_failed: prep.parseFailed, duration_ms: Date.now() - t0, partial_pages: prep.partialPages, system_error: msg, @@ -2262,6 +2268,7 @@ async function ingestPassScoped(args: CliArgs, state: IngestState, scope: Transc written: 0, skipped_secret: prep.skippedSecret + (r.scannerFailed ? 1 : 0), failed: prep.parseFailed + prep.prepared.length, + parse_failed: prep.parseFailed, duration_ms: Date.now() - t0, system_error: r.error, }; @@ -2287,7 +2294,7 @@ async function ingestPassScoped(args: CliArgs, state: IngestState, scope: Transc const msg = `EGRESS_RECEIPT_FAILED: ${(err as Error).message} — ingest refused`; console.error(`[memory-ingest] ERR: ${msg}`); if (resumed && !args.scanSecrets) cleanupStagingDir(resumed.stagingDir); - return { ...base, state_untouched: true, written: 0, failed: prep.parseFailed + prep.prepared.length, duration_ms: Date.now() - t0, system_error: msg }; + return { ...base, state_untouched: true, written: 0, failed: prep.parseFailed + prep.prepared.length, parse_failed: prep.parseFailed, duration_ms: Date.now() - t0, system_error: msg }; } const run: RunContext = { @@ -2343,6 +2350,7 @@ async function ingestPassScoped(args: CliArgs, state: IngestState, scope: Transc ...base, written: run.written, failed: run.failed + prep.parseFailed, + parse_failed: prep.parseFailed, refused: run.refused, unverified: check.unverified, quarantined: run.quarantined, @@ -3236,6 +3244,12 @@ async function runLocked(args: CliArgs): Promise { const t0 = Date.now(); const result = await ingestPass(args, state); + // /sync-gbrain reads the counts here: per-page failures exit 0 (#4417). + if (process.env.GSTACK_INGEST_RESULT_FILE) { + try { + writeFileSync(process.env.GSTACK_INGEST_RESULT_FILE, JSON.stringify({ written: result.written, failed: result.failed, parse_failed: result.parse_failed ?? 0 })); + } catch {} + } if (!result.state_untouched) { // A pending reconcile (set by the upgrade migration or a schema migration) // gets one bounded pass per ingest run until it completes. diff --git a/changelog.d/sync-gbrain-reports-failures.md b/changelog.d/sync-gbrain-reports-failures.md new file mode 100644 index 000000000..7da52d1a8 --- /dev/null +++ b/changelog.d/sync-gbrain-reports-failures.md @@ -0,0 +1,3 @@ +- **One queued record with a malformed path no longer stops artifacts sync for every project.** A skill started where the project slug was empty (for example from `/`) queued `projects//timeline.jsonl`; git staged it under another spelling, the drain refused the whole batch, and every later record waited until the queue was dropped by hand. `gstack-brain-enqueue` now refuses a path with an empty, `.` or `..` component, and the drain drops such a record, syncs the rest, and reports it (#4445). +- **A failed artifacts push stays reported until a push succeeds.** A later drain with nothing new to commit used to write `idle` over `push_failed` while the commits were still unpushed, and /sync-gbrain printed "curated artifacts pushed" because `gstack-brain-sync` exits 0 on a failed push. The status now stays `push_failed`, and the brain-sync row reads the drain's status. It says "pushed" only after a push, "nothing new to push" when there was nothing to send, and `ERR artifacts not pushed (...)` otherwise (#4418). +- **The /sync-gbrain memory row no longer says OK when pages failed to import.** It read only the ingest's exit code, which stays 0 for per-page failures, so it printed `OK ... 126 failed`. The row now reads the ingest's counts: `WARN` when some pages failed, `ERR` when pages failed and none imported, with the failed count and the first cause. A transcript that cannot be parsed is listed as a note and leaves the row `OK` (#4417). diff --git a/docs/gbrain-sync-errors.md b/docs/gbrain-sync-errors.md index aba6258e7..3c3fc7e7e 100644 --- a/docs/gbrain-sync-errors.md +++ b/docs/gbrain-sync-errors.md @@ -465,6 +465,39 @@ If it stays at zero, re-register the source with `gstack-gbrain-source-wireup`. --- +## `artifacts not pushed (push_failed: ...; details: gstack-brain-sync --status)` + +**Problem.** `/sync-gbrain`'s brain-sync stage is `ERR`. + +**Cause.** The artifacts push failed, was blocked, or stopped before +committing (`push_failed`, `blocked` or `error`). The commits and queue are +kept and retried. A failed push stays `push_failed` until a push succeeds, +even when later runs have nothing new to commit. Before this release the +stage read only the exit code and said "curated artifacts pushed". + +**Fix.** Run `gstack-brain-sync --status` and follow the fix its message +names (usually `gh auth status`, or a merge conflict to resolve in +`~/.gstack`). + +--- + +## `BRAIN_SYNC: dropped queued record(s) with a malformed path` + +**Problem.** A queued sync record named an absolute path, or a path with an +empty, `.` or `..` component, such as `projects//timeline.jsonl` from a +skill started where the project slug was empty (the working directory `/`). + +**Cause.** Git stages such a path under another spelling, so the drain used +to refuse the whole batch and every later record waited behind it. The drain +now drops the record, syncs the rest, and lists the dropped paths in +`~/.gstack/.brain-sync-drops.json`. `gstack-brain-enqueue` refuses these +paths, so new ones are not queued. + +**Fix.** Nothing to do. A stray `~/.gstack/projects/timeline.jsonl` left by +such a run is local only and can be deleted. + +--- + ## `[gbrain-sync] gbrain source : path unavailable (); gstack skips it.` **Problem.** A gbrain code source points at a directory that no longer diff --git a/sync-gbrain/SKILL.md b/sync-gbrain/SKILL.md index 56942cd94..455176629 100644 --- a/sync-gbrain/SKILL.md +++ b/sync-gbrain/SKILL.md @@ -352,6 +352,16 @@ still run. State is persisted to `~/.gstack/.gbrain-sync-state.json` via tmp-file + atomic rename. Concurrent runs are blocked by a lock file at `~/.gstack/.sync-gbrain.lock` (5-min stale-takeover). +Report each stage row as printed, never better than it is: +- **memory**: `OK` only when no page failed. `WARN` means some pages failed and + `ERR` means pages failed and none imported; give the failed count and the + first cause from the row, and say failed pages retry next run. +- **brain-sync**: say artifacts were pushed only when the row says + `curated artifacts pushed`. `nothing new to push` means this run had nothing + to send; `artifacts not pushed (: ...)` means the push failed, was + blocked or stopped, and the commits and queue are kept for the next run. + Point the user at `gstack-brain-sync --status` for the cause. + --- ## Step 3: Code-index health check @@ -679,9 +689,9 @@ transient or machine-local failure. Agents must not treat unknown as ready. ## Status reporting End with a Completion Status (per the preamble protocol): -- **DONE** — all stages green, CLAUDE.md guidance block present, verdict GREEN. -- **DONE_WITH_CONCERNS** — sync ran but at least one stage failed or capability - read was unverified. List which and preserve retry guidance. +- **DONE** — all stages `OK`, CLAUDE.md guidance block present, verdict GREEN. +- **DONE_WITH_CONCERNS** — sync ran but at least one stage is `WARN` or `ERR`, or + the capability read was unverified. List which and preserve retry guidance. - **BLOCKED** — could not acquire lock, gbrain not on PATH, or per-repo policy is deny. State the blocker. - **NEEDS_CONTEXT** — /setup-gbrain has not been run, or `gbrain doctor` shows diff --git a/sync-gbrain/SKILL.md.tmpl b/sync-gbrain/SKILL.md.tmpl index 3612a62da..e757826fa 100644 --- a/sync-gbrain/SKILL.md.tmpl +++ b/sync-gbrain/SKILL.md.tmpl @@ -280,6 +280,16 @@ still run. State is persisted to `~/.gstack/.gbrain-sync-state.json` via tmp-file + atomic rename. Concurrent runs are blocked by a lock file at `~/.gstack/.sync-gbrain.lock` (5-min stale-takeover). +Report each stage row as printed, never better than it is: +- **memory**: `OK` only when no page failed. `WARN` means some pages failed and + `ERR` means pages failed and none imported; give the failed count and the + first cause from the row, and say failed pages retry next run. +- **brain-sync**: say artifacts were pushed only when the row says + `curated artifacts pushed`. `nothing new to push` means this run had nothing + to send; `artifacts not pushed (: ...)` means the push failed, was + blocked or stopped, and the commits and queue are kept for the next run. + Point the user at `gstack-brain-sync --status` for the cause. + --- ## Step 3: Code-index health check @@ -607,9 +617,9 @@ transient or machine-local failure. Agents must not treat unknown as ready. ## Status reporting End with a Completion Status (per the preamble protocol): -- **DONE** — all stages green, CLAUDE.md guidance block present, verdict GREEN. -- **DONE_WITH_CONCERNS** — sync ran but at least one stage failed or capability - read was unverified. List which and preserve retry guidance. +- **DONE** — all stages `OK`, CLAUDE.md guidance block present, verdict GREEN. +- **DONE_WITH_CONCERNS** — sync ran but at least one stage is `WARN` or `ERR`, or + the capability read was unverified. List which and preserve retry guidance. - **BLOCKED** — could not acquire lock, gbrain not on PATH, or per-repo policy is deny. State the blocker. - **NEEDS_CONTEXT** — /setup-gbrain has not been run, or `gbrain doctor` shows diff --git a/test/brain-sync.test.ts b/test/brain-sync.test.ts index 6ff7036ef..88d5e4a83 100644 --- a/test/brain-sync.test.ts +++ b/test/brain-sync.test.ts @@ -1568,6 +1568,72 @@ describe('gstack-brain-sync per-file hold', () => { expect(statusJson().message).toContain('not pushed yet'); }); + // #4418: a drain whose queue held records but committed nothing used to + // write idle over a push_failed whose commits were still unpushed. + for (const [name, requeue] of [ + ['a queued file with no new changes', (CLEAN_PATH: string) => run(['gstack-brain-enqueue', CLEAN_PATH])], + ['a queued file that is gone from disk', () => run(['gstack-brain-enqueue', 'projects/p/ceo-plans/gone.md'])], + ] as const) { + test(`a push that keeps failing stays push_failed after a drain of ${name} (#4418)`, () => { + init(); + write(CLEAN, '# a plan\n'); + drain(); + const hook = path.join(bareRemote, 'hooks', 'pre-receive'); + fs.writeFileSync(hook, '#!/bin/sh\necho "403 forbidden" >&2\nexit 1\n', { mode: 0o755 }); + write(CLEAN, '# a plan, revised\n'); + drain(); + expect(statusJson().status).toBe('push_failed'); + requeue(CLEAN); + expect(spoolFiles()).toHaveLength(1); + drain(); + expect(spoolFiles()).toEqual([]); + const s = statusJson(); + expect(s.status).toBe('push_failed'); + expect(s.message).toContain('1 local commit(s) are not pushed yet'); + expect(run(['gstack-brain-sync', '--attention']).stdout).toContain('status=push_failed'); + fs.rmSync(hook); + fs.writeFileSync(path.join(tmpHome, '.brain-last-push-attempt'), '0'); + drain(); + expect(statusJson().status).not.toBe('push_failed'); + expect(remoteShow(CLEAN).stdout).toContain('revised'); + }); + } + + // #4445: a skill started where the project slug is empty spooled + // projects//timeline.jsonl; git staged it as projects/timeline.jsonl, the + // index check refused the batch, and every later record waited behind it. + test('enqueue refuses a path with an empty, "." or ".." component (#4445)', () => { + init(); + for (const bad of ['projects//timeline.jsonl', '/projects/p/timeline.jsonl', 'projects/p/', 'projects/./p/timeline.jsonl', 'projects/../timeline.jsonl']) { + const r = run(['gstack-brain-enqueue', bad]); + expect(r.status).not.toBe(0); + expect(r.stderr).toContain('malformed path'); + } + expect(spoolFiles()).toEqual([]); + expect(run(['gstack-brain-enqueue', CLEAN]).status).toBe(0); + expect(spoolFiles()).toHaveLength(1); + }); + + test('a malformed queued path is dropped and reported; the rest of the queue syncs (#4445)', () => { + init(); + fs.writeFileSync(path.join(tmpHome, 'projects/timeline.jsonl'), '{"skill":"codex","event":"started"}\n'); + seedSpool('{"file":"projects//timeline.jsonl","ts":"2026-11-17T13:06:00Z"}'); + write(CLEAN, '# a plan\n'); + const r = drain(); + expect(r.status).toBe(0); + expect(r.stderr).toContain('1 queued record(s) with a malformed path'); + const s = statusJson(); + expect(s.status).toBe('ok'); + expect(s.message).toContain('pushed 1 file(s)'); + expect(s.message).toContain('dropped 1 queued record(s) with a malformed path'); + expect(remoteFiles()).toContain(CLEAN); + expect(remoteFiles()).not.toContain('projects/timeline.jsonl'); + expect(staged()).toBe(''); + expect(spoolFiles()).toEqual([]); + const drops = JSON.parse(fs.readFileSync(path.join(tmpHome, '.brain-sync-drops.json'), 'utf-8')); + expect(drops.dropped.invalid).toEqual(['projects//timeline.jsonl']); + }); + describe('coupled groups (decision log and its active snapshot)', () => { test('a clean update publishes the group in one commit', () => { init(); diff --git a/test/gstack-gbrain-sync-transcript-mode.test.ts b/test/gstack-gbrain-sync-transcript-mode.test.ts index ac09c8142..70d365e2c 100644 --- a/test/gstack-gbrain-sync-transcript-mode.test.ts +++ b/test/gstack-gbrain-sync-transcript-mode.test.ts @@ -164,6 +164,14 @@ case "$1" in fi echo '${sources}' ;; import) + if [ -n "$GBRAIN_REFUSE_IMPORTS" ]; then + ( cd "$2" && find . -name '*.md' -type f | sed 's#^[.]/##' ) | while read -r p; do + echo " Warning: skipped $p: Managed import must run on the active canonical owner for the selected source." >&2 + done + n=$( cd "$2" && find . -name '*.md' -type f | wc -l | tr -d ' ') + echo "{\\"status\\":\\"success\\",\\"imported\\":0,\\"skipped\\":0,\\"errors\\":$n,\\"total_files\\":$n}" + exit 0 + fi # One import per gbrain source (A4): pages of one ingest run accumulate; # a new run (different parent pid) starts a fresh list. if [ "$(cat "${stagedList}.ppid" 2>/dev/null)" != "$PPID" ]; then echo "$PPID" > "${stagedList}.ppid"; : > "${stagedList}"; fi @@ -459,3 +467,49 @@ describe.skipIf(process.platform === "win32")("memory stage transcript consent", } }); }); + +// #4417: gstack-memory-ingest exits 0 when gbrain refuses single pages (they +// are retried next run), and the memory row used to read only that exit code, +// so it printed OK with every page refused. +describe.skipIf(process.platform === "win32")("memory stage failure counts (#4417)", () => { + test("pages gbrain refuses make the row ERR with the count and the first cause", () => { + const sb = sandbox(); + try { + const r = runSync(sb, ["--incremental"], { GBRAIN_REFUSE_IMPORTS: "1" }); + const stage = memoryStage(sb) as { ok: boolean; warn?: boolean; summary: string }; + expect(stage.ok).toBe(false); + expect(stage.summary).toMatch(/^0 imported, [1-9][0-9]* failed [(]retried next run/); + expect(stage.summary).toContain("Managed import must run on the active canonical owner"); + expect(r.stdout).toMatch(/ERR +memory +0 imported, [1-9][0-9]* failed/); + expect(r.stdout).not.toMatch(/OK +memory/); + expect(r.status).toBe(1); + + // The refusal clears: the same pages import and the row is OK again. + const ok = runSync(sb, ["--incremental"]); + expect(ok.status).toBe(0); + expect(memoryStage(sb).ok).toBe(true); + expect(ok.stdout).toMatch(/OK +memory/); + } finally { + sb.cleanup(); + } + }); + + // A transcript that cannot be parsed is never stamped, so it is counted on + // every run; it must not turn the row ERR for good. + test("an unparseable transcript is a note on an OK row, every run", () => { + const sb = sandbox({ mode: "all" }); + try { + writeFileSync(join(sb.home, ".claude", "projects", "work-acme", "empty0001.jsonl"), ""); + for (let run = 0; run < 2; run++) { + const r = runSync(sb, ["--incremental"]); + const stage = memoryStage(sb) as { ok: boolean; warn?: boolean; summary: string }; + expect(stage.ok).toBe(true); + expect(stage.warn).toBeUndefined(); + expect(stage.summary).toContain("1 source file(s) could not be parsed and were skipped"); + expect(r.status).toBe(0); + } + } finally { + sb.cleanup(); + } + }); +}); diff --git a/test/gstack-gbrain-sync.test.ts b/test/gstack-gbrain-sync.test.ts index 32bf537c2..63cf693a5 100644 --- a/test/gstack-gbrain-sync.test.ts +++ b/test/gstack-gbrain-sync.test.ts @@ -10,11 +10,13 @@ import { describe, it, expect, beforeEach, afterEach } from "bun:test"; import { mkdtempSync, writeFileSync, readFileSync, existsSync, rmSync, mkdirSync, chmodSync, symlinkSync } from "fs"; import { tmpdir } from "os"; -import { join } from "path"; +import { dirname, join } from "path"; import { spawnSync } from "child_process"; import { + brainSyncStageVerdict, derivePathOnlyHashLegacyId, + memoryStageVerdict, planHostnameFoldMigration, sourceLocalPath, _resetGbrainSupportsRenameCache, @@ -544,10 +546,11 @@ esac rmSync(home, { recursive: true, force: true }); }); - // A5 (#2670): a successful git push is not gbrain indexing. + // A5 (#2670): a successful git push is not gbrain indexing. Artifacts sync is + // off here, so the row says nothing was pushed (#4418) and still checks gbrain. for (const [pageCount, ok, expected] of [ [0, false, "gbrain source fixture-artifacts has 0 indexed pages. Fix: gbrain sync --source fixture-artifacts"], - [7, true, "curated artifacts pushed; gbrain source fixture-artifacts has 7 pages"], + [7, true, "nothing was pushed; gbrain source fixture-artifacts has 7 pages"], ] as const) { it(`brain-sync stage reports the artifacts source's ${pageCount} indexed pages (ok=${ok})`, () => { const home = makeTestHome(); @@ -574,6 +577,68 @@ esac }); } + // #4418: gstack-brain-sync --once exits 0 when its push fails, so the row + // must come from the drain's status, and a failed push stays failed on the + // runs after it until a push succeeds. + it.skipIf(process.platform === "win32")("brain-sync stage says pushed only when the push went through (#4418)", () => { + const home = makeTestHome(); + const gstackHome = join(home, ".gstack"); + const fakeBin = join(home, "fake-bin"); + const remote = join(home, "remote.git"); + mkdirSync(gstackHome, { recursive: true }); + mkdirSync(fakeBin, { recursive: true }); + writeFileSync(join(fakeBin, "gbrain"), `#!/bin/sh +case "$*" in + "sources list --json") printf '%s\\n' '{"sources":[{"id":"fixture-artifacts","local_path":"${gstackHome}","page_count":7}]}' ;; + *) exit 1 ;; +esac +`); + chmodSync(join(fakeBin, "gbrain"), 0o755); + const env = { + HOME: home, + GSTACK_HOME: gstackHome, + GIT_CONFIG_NOSYSTEM: "1", + GIT_CONFIG_GLOBAL: join(home, ".gitconfig"), + PATH: `${fakeBin}:${process.env.PATH || ""}`, + }; + const bin = (name: string, ...args: string[]) => + spawnSync(join(import.meta.dir, "..", "bin", name), args, { encoding: "utf-8", timeout: 60000, env: { ...process.env, ...env } }); + const plan = join(gstackHome, "projects", "p", "ceo-plans", "plan.md"); + const brainSyncRow = () => { + const r = runScript(["--incremental", "--no-code", "--no-memory", "--quiet"], env); + const state = JSON.parse(readFileSync(join(gstackHome, ".gbrain-sync-state.json"), "utf-8")); + return { exitCode: r.exitCode, stage: state.last_stages.find((entry: { name: string }) => entry.name === "brain-sync") }; + }; + try { + spawnSync("git", ["init", "--bare", "-q", "-b", "main", remote], { timeout: 30000 }); + expect(bin("gstack-artifacts-init", "--remote", remote).status).toBe(0); + expect(bin("gstack-config", "set", "artifacts_sync_mode", "full").status).toBe(0); + mkdirSync(dirname(plan), { recursive: true }); + writeFileSync(plan, "# a plan\n"); + bin("gstack-brain-enqueue", "projects/p/ceo-plans/plan.md"); + let row = brainSyncRow(); + expect(row.stage.summary).toMatch(/^curated artifacts pushed.*gbrain source fixture-artifacts has 7 pages/); + expect(row.stage.ok).toBe(true); + + writeFileSync(join(remote, "hooks", "pre-receive"), '#!/bin/sh\necho "403 forbidden" >&2\nexit 1\n', { mode: 0o755 }); + writeFileSync(plan, "# a plan, revised\n"); + bin("gstack-brain-enqueue", "projects/p/ceo-plans/plan.md"); + row = brainSyncRow(); + expect(row.stage.ok).toBe(false); + expect(row.stage.summary).toContain("artifacts not pushed (push_failed: push failed"); + expect(row.stage.summary).not.toContain("pushed to git"); + expect(row.exitCode).toBe(1); + + // The next run still reports the failure, not "pushed". + bin("gstack-brain-enqueue", "projects/p/ceo-plans/plan.md"); + row = brainSyncRow(); + expect(row.stage.ok).toBe(false); + expect(row.stage.summary).toContain("artifacts not pushed (push_failed: "); + } finally { + rmSync(home, { recursive: true, force: true }); + } + }, 60_000); + it("brain-sync stage resolves the sibling binary, not a HOME-rooted path", () => { // Regression for Codex M9: pre-fix the orchestrator looked up // ~/.claude/skills/gstack/bin/gstack-brain-sync, which silently no-op'd @@ -1189,3 +1254,43 @@ esac expect(commands).not.toMatch(/^sync /m); }); }); + +describe("stage verdicts (#4417, #4418)", () => { + const noGbrain = { PATH: "/nonexistent" }; + + it("memory: failed pages beside imported ones are WARN with the count and first cause", () => { + const v = memoryStageVerdict(0, "[memory-ingest] FAILED a.md: refused\n[memory-ingest] done\n", { written: 3, failed: 2 }); + expect(v).toMatchObject({ ok: true, warn: true }); + expect(v.summary).toMatch(/^3 imported, 2 failed [(]retried next run/); + expect(v.summary).toContain("first: a.md: refused"); + }); + + it("memory: parse failures are a note, not an import failure", () => { + const v = memoryStageVerdict(0, "[memory-ingest] done\n", { written: 0, failed: 2, parse_failed: 2 }); + expect(v).toEqual({ ok: true, summary: "done; 2 source file(s) could not be parsed and were skipped" }); + const mixed = memoryStageVerdict(0, "", { written: 0, failed: 3, parse_failed: 1 }); + expect(mixed.ok).toBe(false); + expect(mixed.summary).toMatch(/^0 imported, 2 failed .*; 1 source file[(]s[)] could not be parsed/); + }); + + it("memory: a non-zero exit or a signal is ERR whatever the counts", () => { + expect(memoryStageVerdict(2, "[memory-ingest] ERR: gbrain missing\n", { written: 0, failed: 0 })).toEqual({ ok: false, summary: "gbrain missing (exit 2)" }); + expect(memoryStageVerdict(null, "", null)).toEqual({ ok: false, summary: "ingest pass complete (killed by signal / timeout)" }); + }); + + for (const [status, ok, warn, lead] of [ + ["idle", true, undefined, "nothing new to push (queue empty)"], + ["held", true, true, "artifacts not all pushed (held: queue empty;"], + ["collision", true, true, "artifacts not all pushed (collision: queue empty;"], + ["error", false, undefined, "artifacts not pushed (error: queue empty;"], + ["blocked", false, undefined, "artifacts not pushed (blocked: queue empty;"], + [42, false, undefined, "artifacts not pushed (unknown: queue empty;"], + ] as const) { + it(`brain-sync: drain status ${status} reads ok=${ok} warn=${warn}`, () => { + const v = brainSyncStageVerdict({ status, message: "queue empty" }, noGbrain); + expect(v.ok).toBe(ok); + expect(v.warn).toBe(warn); + expect(v.summary.startsWith(lead)).toBe(true); + }); + } +});