0.4.0 backlog integration: 26 PRs + What's-new (#2001) + hermetic night gates (#2009)

.notturno/gates

@@ -18,8 +18,20 @@
 #              loopback suites below (fleet-dependent; they self-skip without
 #              an sshd and mutate ~/.ssh/authorized_keys when one exists).
 #              Vault-dependent tests self-skip on their own existsSync/env
-#              guards, exactly as in CI. A `pnpm -r run build` precedes the
-#              suites, as in CI (several suites read built bundles).
+#              guards, exactly as in CI. A `pnpm -r run build` (step `build`)
+#              precedes the suites, as in CI (several suites read built bundles).
+#              The suites run in CI's environment (#2007), not the sandbox's:
+#              a scrubbed env (`env -i` + PATH/TMPDIR/locale/USER) with CI=true,
+#              GITHUB_ACTIONS=true, RUNNER_TEMP, GITHUB_BASE_REF=<base> (a
+#              pull_request run), TZ=UTC, and a fresh EMPTY scratch HOME — the
+#              GitHub runner's HOME has no ~/.amico, no ~/.config/opencode, no
+#              fleet; the sandbox's HOME has the implementer's opencode config
+#              and the env carries AWS/GH tokens + NOTTURNO_*, which tests read.
+#              A red suite names its failing test files (first 5) in RESULT:
+#                failed: vitest:extension [test/a.test.ts, test/b.test.ts]
+#              Divergences the gate cannot erase are printed as `warn:` lines:
+#              node major != CI's 20, running as root (CI's runner is not —
+#              chmod-000 tests cannot fail for root).
 # NOT here (need the vendored engine binary / bun materialization / Julia /
 # PyPI): build-binary, engine-tests, vsix-gate, boot-smoke, schema-roundtrip.
 #
@@ -30,7 +42,9 @@
 #                          Unset/unresolvable → the nearest of origin/lane/* and
 #                          origin/main (fewest commits from merge-base to HEAD).
 #                          No base at all → every package's suite runs.
-#   NOTTURNO_GATES_STEPS   comma list subset of drift,typecheck,vitest (default all)
+#   NOTTURNO_GATES_STEPS   comma list subset of drift,typecheck,build,vitest (default all;
+#                          build only runs when vitest has packages to test)
+#   NOTTURNO_GATES_HERMETIC=0  run the suites in the ambient env/HOME (debugging only)
 set -uo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -45,16 +59,16 @@ PLAN=0
 for a in "$@"; do
   case "$a" in
     --plan) PLAN=1 ;;
-    -h|--help) sed -n '2,36p' "$0"; exit 0 ;;
+    -h|--help) sed -n '2,52p' "$0"; exit 0 ;;
     *) echo "[notturno-gates] RESULT: RED — unknown argument: $a"; exit 2 ;;
   esac
 done
 
-STEPS="${NOTTURNO_GATES_STEPS:-drift,typecheck,vitest}"
+STEPS="${NOTTURNO_GATES_STEPS:-drift,typecheck,build,vitest}"
 for s in ${STEPS//,/ }; do
   case "$s" in
-    drift|typecheck|vitest) ;;
-    *) echo "[notturno-gates] RESULT: RED — unknown step '$s' in NOTTURNO_GATES_STEPS (known: drift,typecheck,vitest)"; exit 2 ;;
+    drift|typecheck|build|vitest) ;;
+    *) echo "[notturno-gates] RESULT: RED — unknown step '$s' in NOTTURNO_GATES_STEPS (known: drift,typecheck,build,vitest)"; exit 2 ;;
   esac
 done
 want() { case ",$STEPS," in *",$1,"*) return 0 ;; *) return 1 ;; esac; }
@@ -146,38 +160,125 @@ PASSED=""
 FAILED=""
 HINTS=""
 T0=$SECONDS
+STEP_DETAIL="" # a step may set this to a short " [..]" suffix for the RESULT line
 step() { # step <name> <hint-on-failure> <cmd...>
   local name="$1" hint="$2" t=$SECONDS rc
   shift 2
+  STEP_DETAIL=""
   say "── $name: $*"
   "$@"
   rc=$?
   if [ "$rc" -eq 0 ]; then
     PASSED="$PASSED $name"
     say "── $name: ok ($((SECONDS - t))s)"
   else
-    FAILED="$FAILED $name"
+    FAILED="$FAILED $name$STEP_DETAIL"
     [ -n "$hint" ] && HINTS="$HINTS $hint;"
-    say "── $name: FAIL exit $rc ($((SECONDS - t))s)"
+    say "── $name: FAIL exit $rc ($((SECONDS - t))s)${STEP_DETAIL}"
+  fi
+}
+
+# ── CI's environment for the vitest suites (#2007) ───────────────────────────
+SCRATCH="$(mktemp -d "${TMPDIR:-/tmp}/notturno-gates.XXXXXX")" || { echo "[notturno-gates] RESULT: RED — mktemp failed"; exit 2; }
+trap 'chmod -R u+rwx "$SCRATCH" 2>/dev/null; rm -rf "$SCRATCH"' EXIT
+CI_TMP="$SCRATCH/tmp"
+mkdir -p "$CI_TMP" "$SCRATCH/runner-temp"
+
+# run a command the way CI's `fast` job runs a test step
+ci_env() {
+  if [ "${NOTTURNO_GATES_HERMETIC:-1}" = "0" ]; then "$@"; return; fi
+  local home
+  home="$(mktemp -d "$SCRATCH/home.XXXXXX")" || return 2  # fresh + empty per suite
+  local keep=() v
+  for v in PATH LANG LC_ALL USER LOGNAME SHELL; do
+    [ -n "${!v:-}" ] && keep+=("$v=${!v}")
+  done
+  env -i "${keep[@]}" \
+    HOME="$home" TMPDIR="$CI_TMP" RUNNER_TEMP="$SCRATCH/runner-temp" TZ=UTC \
+    CI=true GITHUB_ACTIONS=true ${BASE:+GITHUB_BASE_REF="${BASE#origin/}"} \
+    "$@"
+}
+
+vitest_bin() { # the package's own vitest bin (no pnpm/corepack under the scratch HOME)
+  if [ -x "packages/$1/node_modules/.bin/vitest" ]; then echo "$ROOT/packages/$1/node_modules/.bin/vitest"; else echo ""; fi
+}
+
+# failed_files <vitest-json> [quarantine-gate-log] → "test/a.test.ts, test/b.test.ts, +N more" (first 5)
+failed_files() {
+  node - "$@" <<'NODE' 2>/dev/null
+const fs = require("fs"), path = require("path");
+const [json, gateLog] = process.argv.slice(2);
+const files = [];
+const add = (f) => { if (f && !files.includes(f)) files.push(f); };
+if (gateLog && fs.existsSync(gateLog)) {
+  // quarantine-gate violations: "... FAIL <kind> <suite>::<file>::<test>: ..."
+  for (const m of fs.readFileSync(gateLog, "utf8").matchAll(/ FAIL [\w-]+ [^:\s]+::([^:]+)::/g)) add(m[1]);
+}
+if (!files.length && json && fs.existsSync(json)) {
+  let r; try { r = JSON.parse(fs.readFileSync(json, "utf8")); } catch { r = null; }
+  for (const t of (r && r.testResults) || []) {
+    const bad = t.status === "failed" || (t.assertionResults || []).some((a) => a.status === "failed");
+    if (bad) add(path.relative(process.env.PKG_DIR || process.cwd(), t.name));
+  }
+}
+if (files.length) {
+  const head = files.slice(0, 5);
+  if (files.length > 5) head.push(`+${files.length - 5} more`);
+  process.stdout.write(head.join(", "));
+}
+NODE
+}
+
+set_detail() { # set_detail <pkg> <json> [gate-log]
+  local f
+  f="$(PKG_DIR="$ROOT/packages/$1" failed_files "$2" "${3:-}")"
+  [ -n "$f" ] && STEP_DETAIL=" [$f]"
+  return 0
+}
+
+vitest_args() { # common CI flags + exclusions + a JSON report
+  local g
+  VARGS=(run --passWithNoTests --exclude '**/slow/**')
+  for g in $ENV_DEPENDENT_EXCLUDES; do VARGS+=(--exclude "$g"); done
+  VARGS+=(--reporter=default --reporter=json "--outputFile.json=$1")
+}
+
+run_vitest() { # run_vitest <pkg> <json>
+  local bin
+  bin="$(vitest_bin "$1")"
+  vitest_args "$2"
+  if [ -n "$bin" ]; then
+    (cd "packages/$1" && ci_env "$bin" "${VARGS[@]}")
+  else
+    (cd "packages/$1" && ci_env pnpm exec vitest "${VARGS[@]}")
   fi
 }
 
 run_amico_run_suite() {
-  local out vexit excl=() g
-  out="${TMPDIR:-/tmp}/notturno-amico-run-$$.json"
-  for g in $ENV_DEPENDENT_EXCLUDES; do excl+=(--exclude "$g"); done
-  (cd packages/amico-run && pnpm exec vitest run --passWithNoTests --exclude '**/slow/**' "${excl[@]}" \
-      --reporter=default --reporter=json --outputFile.json="$out")
+  local out="$SCRATCH/vitest-amico-run.json" glog="$SCRATCH/quarantine-amico-run.log" vexit qexit
+  run_vitest amico-run "$out"
   vexit=$?
-  (cd packages/amico-run && node ../../scripts/test_quarantine_gate.mjs --runner-exit "$vexit" "$out")
+  (cd packages/amico-run && node ../../scripts/test_quarantine_gate.mjs --runner-exit "$vexit" "$out") 2>&1 | tee "$glog"
+  qexit=${PIPESTATUS[0]}
+  [ "$qexit" -ne 0 ] && set_detail amico-run "$out" "$glog"
+  return "$qexit"
 }
 
 run_pkg_suite() {
-  local p="$1" excl=() g
-  for g in $ENV_DEPENDENT_EXCLUDES; do excl+=(--exclude "$g"); done
-  (cd "packages/$p" && pnpm exec vitest run --passWithNoTests --exclude '**/slow/**' "${excl[@]}")
+  local p="$1" out="$SCRATCH/vitest-$1.json" rc
+  run_vitest "$p" "$out"
+  rc=$?
+  [ "$rc" -ne 0 ] && set_detail "$p" "$out"
+  return "$rc"
 }
 
+if want vitest && [ -n "$SELECTED" ]; then
+  NODE_MAJOR="$(node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo '?')"
+  say "vitest env: $([ "${NOTTURNO_GATES_HERMETIC:-1}" = "0" ] && echo 'AMBIENT (NOTTURNO_GATES_HERMETIC=0)' || echo "CI mirror — env -i, CI=true GITHUB_ACTIONS=true TZ=UTC, scratch HOME under $SCRATCH${BASE:+, GITHUB_BASE_REF=${BASE#origin/}}"); node $(node --version 2>/dev/null || echo '?')"
+  [ "$NODE_MAJOR" != "20" ] && say "warn: node major $NODE_MAJOR != CI's 20 (actions/setup-node node-version: 20) — a red that CI would not show may be a node-version difference"
+  [ "$(id -u 2>/dev/null)" = "0" ] && say "warn: running as root — CI's runner is unprivileged; permission tests (chmod 000/0500 dirs) cannot fail for root"
+fi
+
 if want drift; then
   step drift "overlay edit without a manifest refresh? run 'node packages/app-bundle/scripts/refresh_manifest.mjs' then drift_gate, and commit manifest.json" \
     node packages/app-bundle/scripts/drift_gate.mjs
@@ -186,7 +287,7 @@ if want typecheck; then
   step typecheck "" pnpm -r run typecheck
 fi
 if want vitest && [ -n "$SELECTED" ]; then
-  step build "" pnpm -r run build
+  want build && step build "" pnpm -r run build
   for p in $SELECTED; do
     if [ "$p" = "amico-run" ]; then
       step "vitest:$p" "" run_amico_run_suite

CONTEXT.md

@@ -301,6 +301,18 @@ _Avoid_: Explorer (VS Code's native file explorer is separate), Panel (the in-ap
 The multi-document file workspace in the side panel. Holds zero or more files as inner tabs, each rendering its content (markdown rendered with a toggle to edit; text/code files in a CodeMirror editor; images and PDFs inline). Files arrive via Sidebar single-click or a Chat file pill and accumulate as tabs — each closeable and drag-reorderable; opening an already-open file focuses its existing tab rather than duplicating it. A breadcrumb bar under each pane's tab strip shows the active file's project-relative path with interactive sibling navigation. Supports recursive split panes via edge-drop: dragging a tab toward a pane's edge divides the view, and each resulting pane keeps its own tab bar, breadcrumb, zoom, and preview/edit toggle. Empty panes auto-collapse; a minimum pane dimension is enforced so splits can't shrink below a usable size. Opens and activates automatically when the first file is selected; shows a placeholder when no file is open. For committed editing, double-click the Sidebar entry to open a native VS Code tab.
 _Avoid_: Editor (Preview is a multi-document viewer, not a primary editor — committed editing belongs in a native VS Code tab), File browser (the Sidebar is still the primary project-wide file tree; the breadcrumb is a contextual sibling-navigation aid scoped to the open file, not a second tree)
 
+**Paper Mode**:
+A first-class, opt-in session surface for *committed* LaTeX co-editing: the `.tex` editor is primary, Chat docks beneath it, and the compiled PDF sits to the right. Distinct from Preview (which stays a viewer) and from the Work Column layout — Paper Mode is its own layout, not a resize of an existing one. The live editor Draft is the single source of truth; the agent reads it fresh each turn; agent edits arrive as reviewable Pending Hunks rather than direct disk writes; and compilation is manual. Does not depend on the paused wide-mode work.
+_Avoid_: Write mode (superseded name), Overleaf mode, wide mode (a separate, paused feature)
+
+**Draft** (Paper Mode):
+The live in-editor content of a `.tex` file, versioned by a monotonic Content Revision. In Paper Mode it is the single source of truth: the human's typing and accepted agent edits both land here, saves flush it to disk, and the agent always reads it at its current revision. Supersedes disk and any cached copy as the authority for "current content."
+_Avoid_: Buffer (implementation detail), file contents (ambiguous with disk)
+
+**Pending Hunk**:
+A proposed agent edit shown as an inline, reviewable diff decoration in the Paper Mode editor, not yet written to the Draft or disk. Accepted (`✓`) hunks apply to the Draft; rejected (`✗`) hunks vanish. A Pending Hunk that overlaps concurrent human edits becomes a Conflict Hunk requiring explicit resolution — nothing lands unchecked. Only accepted hunks emit mutation-ledger receipts and enter the compiled source.
+_Avoid_: Suggestion, agent write (in Paper Mode the agent proposes, it does not write disk), pending change
+
 ### Developer tooling
 
 **Rebuild (local)**:

docs/adr/0038-paper-mode-snapshot-base-3way-merge.md

@@ -0,0 +1,27 @@
+# ADR 0038 — Paper Mode: live-draft source of truth and snapshot-base 3-way merge for AI/human co-editing
+
+Status: proposed (2026-09-28)
+
+Tracking: harmoniqs/amicode#1620 · Glossary: `CONTEXT.md` (Paper Mode, Draft, Pending Hunk)
+
+Paper Mode is a new opt-in session surface for *committed* LaTeX writing (editor primary, Chat docked beneath, PDF right; distinct from Preview, which stays a viewer, and independent of the paused wide-mode work). It exists because Amicode has no safe surface for AI and human to co-edit the same `.tex`: today the agent reads a stale disk/cache snapshot (edits it "saw" go missing from its output), agent writes bypass the editor buffer (the human must reopen the file), concurrent edits clobber silently, and there is no way to review an agent change before it lands or to control when compilation runs.
+
+The decision is fourfold, and each part is hard to reverse because tooling, UI, and the mutation boundary all bind to it:
+
+1. **The live editor Draft is the single source of truth**, versioned by a monotonic Content Revision (extending the content-revision rule ADR-0013 already mandates). In Paper Mode the agent's Read/Edit tools read the Draft *at its current revision every turn* — never disk, never a cache. "The agent always sees my edits" becomes true by construction and checkable, because the revision it read is stamped. This supersedes the coarse revert-based fix in #1422, which only reverts a *clean* buffer and blocks while the human is typing — insufficient for real co-editing.
+
+2. **Agent edits propose to a review layer; they do not write disk.** An agent Edit/Write in Paper Mode produces Pending Hunks — inline diff decorations in the editor — leaving the Draft and disk unchanged until the human accepts. The human's own typing writes the Draft as normal and is always authoritative. Un-accepted agent text is therefore never in the file, which is what makes "the AI never interferes," "human always wins," and "nothing compiles behind my back" all fall out of one mechanism.
+
+3. **Concurrent edits reconcile via a snapshot-base 3-way merge.** The Content Revision the agent read at edit-start is captured as the merge base. At apply time we 3-way merge (base → human-edited Draft, base → agent hunks): non-overlapping regions land as Pending Hunks; regions both parties touched become **Conflict Hunks** the human must resolve. Conflicts are **never auto-resolved** — the human explicitly wanted to be able to check whether their text was removed. CM6's `@codemirror/merge` (already a dependency, already used in `editable-diff-view.tsx`) supplies the merge/decoration primitive.
+
+4. **Compilation is manual, on the accepted Draft.** It fires only on an explicit Compile action and compiles the Draft as it stands — Pending (un-accepted) Hunks are excluded because they are not yet in the file. Accepted hunks emit ADR-0017 mutation-ledger receipts (appearing in Files Changed with real provenance); pending and rejected hunks emit nothing.
+
+## Considered options
+
+- **Agent-writes-disk with a revert-style overlay (today's #1422 model), rejected.** Reachable from current code, but the agent's text *is* in the file before the human approves, so "human always wins," "review before it lands," and "compile only on approve" all become muddy special cases rather than consequences of the model. The dirty-buffer guard also silently blocks agent edits whenever the human is typing, which is the opposite of collaboration.
+- **CRDT live merge (Yjs), rejected for now.** A shared mergeable document gives Google-Docs-style seamlessness, but it is a heavy, hard-to-reverse architectural commitment, and per-hunk human review sits *on top* of it anyway. The snapshot-base 3-way merge delivers the reviewed-collaboration requirement with far less machinery; revisit only if real-time multi-human co-presence becomes a requirement.
+- **Promote Preview into a primary editor, rejected.** Reverses ADR-0013 and the glossary's deliberate "Preview = viewer" boundary and tangles viewer and editor responsibilities in one component. Paper Mode is a separate bounded surface instead.
+
+## Consequences
+
+The agent's Edit/Write tools gain a Paper-Mode-specific behavior (propose to the review layer instead of writing disk), which must fail closed — an agent edit that cannot be expressed as a Pending Hunk is surfaced, not silently written. The Draft/revision authority and the review/merge UI are new machinery, but both build on primitives that already exist (ADR-0013 content revisions, ADR-0017 receipts, `@codemirror/merge`). Paper Mode deliberately does **not** depend on the paused wide-mode work (#1434) and is built as its own layout. LaTeX language intelligence (#1513), SyncTeX (#1432/#1514), an outline navigator, and in-editor search (#1430) are out of scope — they dock into Paper Mode later as independent slices. Revisit this decision only if Amicode adopts real-time multi-human collaboration, at which point option 2 (CRDT) is the successor.

docs/releases/0.3.10.md

@@ -0,0 +1,25 @@
+---
+version: 0.3.10
+date: 2026-10-27
+highlights:
+  - title: Sticky widgets
+    body: >-
+      Opt a widget into "sticky" and it docks as a compact strip when you
+      scroll it out of view, so a live readout stays in sight while the
+      conversation moves on.
+  - title: Step-limited subagents report what they finished
+    body: >-
+      A subagent that runs out of steps now hands back an EXHAUSTED receipt —
+      what it finished and what is left — instead of stopping silently.
+  - title: Specs that file their own issues
+    body: >-
+      "amico spec slices" turns a spec's plan rows into linked GitHub issues,
+      and "amico census" gives a quick read of open work with named gaps and a
+      72-hour stall tripwire.
+  - title: Safer hub deploys
+    body: >-
+      The hub now deploys a lane build with an atomic switch, pinned
+      provenance, and one-step rollback.
+links:
+  notes: https://github.com/harmoniqs/amicode/releases/tag/v0.3.10
+---