instar 1.3.296 → 1.3.298

package/scripts/decision-audit-presence-check.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// safe-git-allow: CI-only gate script — single read-only `git diff --name-status`
+//   against the Actions checkout; runs on ubuntu runners where the TS
+//   SafeGitExecutor is not importable from a standalone .mjs.
+/**
+ * decision-audit-presence-check — gate-bypass detector (task #81 close-out).
+ *
+ * Every commit that touches in-scope files (src/, scripts/, .husky/, skills/
+ * code) is supposed to pass through the local instar-dev pre-commit gate,
+ * which writes + stages a decision-audit record. When the gate is silently
+ * absent — the live case: a worktree created with raw `git worktree add` has
+ * no husky shim, so `git commit` runs ZERO hooks — the commits arrive with no
+ * audit record, and nothing notices. CI re-runs the substantive checks, but
+ * the audit trail has holes and gate-block UX (tier floors, deferral
+ * detection) never fired for those commits.
+ *
+ * Structure > Willpower: this check makes the bypass VISIBLE at the PR
+ * boundary. A PR whose changes include in-scope files must also carry gate
+ * evidence — a per-entry decision file (post-#827: one
+ * `.instar/instar-dev-decisions/<ts>-<slug>.json` added per gate run) or, as
+ * transition grace for PRs authored under the pre-#827 writer, a modification
+ * to the legacy `.instar/instar-dev-decisions.jsonl`.
+ *
+ * Exemptions mirror the eli16 PR gate: bot authors and the automated
+ * release-cut PR.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+// Keep in sync with inScope() in scripts/instar-dev-precommit.js — the gate
+// this check detects bypasses OF. (A drift here only weakens detection, never
+// blocks a legitimate PR: extra in-scope prefixes would require evidence from
+// PRs the local gate also covers.)
+export function isInScopeFile(file) {
+  if (file.startsWith('src/')) return true;
+  if (file.startsWith('scripts/')) return true;
+  if (file.startsWith('.husky/')) return true;
+  if (file.startsWith('skills/') && file.endsWith('SKILL.md')) return true;
+  if (file.startsWith('skills/') && (file.endsWith('.sh') || file.endsWith('.mjs') || file.endsWith('.js'))) return true;
+  return false;
+}
+
+function isGateEvidence(change) {
+  // Post-#827 per-entry file (added per gate evaluation)…
+  if (/^\.instar\/instar-dev-decisions\/.+\.json$/.test(change.file)) return true;
+  // …or the pre-#827 legacy JSONL append (transition grace for in-flight PRs).
+  if (change.file === '.instar/instar-dev-decisions.jsonl') return true;
+  return false;
+}
+
+/**
+ * Pure evaluation — exported for unit tests.
+ * @param {{ changes: Array<{status: string, file: string}>, title?: string, authorType?: string }} input
+ * @returns {{ ok: boolean, exempt?: string, reason?: string, inScopeFiles?: string[] }}
+ */
+export function evaluateDecisionAuditPresence(input) {
+  const title = String(input?.title ?? '');
+  if (String(input?.authorType ?? '') === 'Bot') return { ok: true, exempt: 'bot-author' };
+  if (/^chore:\s*release\b/i.test(title)) return { ok: true, exempt: 'release-cut' };
+
+  const changes = Array.isArray(input?.changes) ? input.changes : [];
+  const inScopeFiles = changes.map((c) => c.file).filter(isInScopeFile);
+  if (inScopeFiles.length === 0) {
+    return { ok: true, reason: 'no in-scope changes — local gate not required' };
+  }
+
+  const hasEvidence = changes.some(isGateEvidence);
+  if (hasEvidence) {
+    return { ok: true, reason: 'gate evidence present', inScopeFiles };
+  }
+
+  return {
+    ok: false,
+    inScopeFiles,
+    reason:
+      `This PR changes ${inScopeFiles.length} in-scope file(s) but carries NO decision-audit record — ` +
+      `the local instar-dev pre-commit gate did not run for these commits. The usual cause is a build ` +
+      `worktree without the husky shim (created with raw 'git worktree add' instead of 'instar worktree ` +
+      `create'). Fix: in the worktree run 'npm run prepare' (wires .husky/_), then re-commit so the gate ` +
+      `evaluates the change and its audit entry (.instar/instar-dev-decisions/<ts>-<slug>.json) rides the ` +
+      `commit. See tasks #81/#80 and PRs #827/#829.`,
+  };
+}
+
+/** Parse `git diff --name-status base...head` output into change records. */
+export function parseNameStatus(text) {
+  const changes = [];
+  for (const line of String(text).split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    // Format: "<STATUS>\t<path>" (renames: "R100\t<old>\t<new>" — take the new path).
+    const parts = t.split('\t');
+    if (parts.length < 2) continue;
+    const status = parts[0];
+    const file = parts[parts.length - 1];
+    changes.push({ status, file });
+  }
+  return changes;
+}
+
+// ── CLI entrypoint (CI) ────────────────────────────────────────────────────
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split('/').pop());
+if (invokedDirectly) {
+  const baseSha = process.env.BASE_SHA;
+  const headSha = process.env.HEAD_SHA;
+  if (!baseSha || !headSha) {
+    console.error('decision-audit gate: BASE_SHA and HEAD_SHA env vars are required.');
+    process.exit(2);
+  }
+  let diffOut;
+  try {
+    diffOut = execFileSync('git', ['diff', '--name-status', `${baseSha}...${headSha}`], { encoding: 'utf8' });
+  } catch (err) {
+    console.error(`decision-audit gate: git diff failed — ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(2);
+  }
+  const res = evaluateDecisionAuditPresence({
+    changes: parseNameStatus(diffOut),
+    title: process.env.PR_TITLE,
+    authorType: process.env.PR_AUTHOR_TYPE,
+  });
+  if (res.ok) {
+    console.log(`decision-audit gate: OK — ${res.exempt ? `exempt (${res.exempt})` : res.reason}`);
+    process.exit(0);
+  }
+  console.error('decision-audit gate: FAIL');
+  console.error(res.reason);
+  console.error('');
+  console.error('In-scope files without gate evidence:');
+  for (const f of res.inScopeFiles ?? []) console.error(`  - ${f}`);
+  process.exit(1);
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T13:08:42.936Z",
-  "instarVersion": "1.3.296",
+  "generatedAt": "2026-06-05T13:55:19.961Z",
+  "instarVersion": "1.3.298",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {
@@ -1506,7 +1506,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "5ab09020e2f4ebe22bee46955eb99c18d4a2fc9aa19e547369d8783d83b2ecc1",
+      "contentHash": "4798aa00b08d4697ccaa2fbdba6224289b7bd21290dad9c4a911c0bfd9bc657f",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {

package/upgrades/1.3.297.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+New `scripts/decision-audit-presence-check.mjs` (pure evaluator + CLI) and `.github/workflows/decision-audit-gate.yml`. The in-scope predicate mirrors `scripts/instar-dev-precommit.js`.
+
+## What to Tell Your User
+
+Nothing user-visible — contributor CI. Pull requests that change gate-scoped code now fail fast if the local pre-commit gate never ran for them (the silent-bypass case), with a message that says exactly how to fix it.
+
+## Summary of New Capabilities
+
+- `decision-audit-gate` CI check: a PR touching src/scripts/.husky/skills code must include a decision-audit record (per-entry file post-#827, or a legacy jsonl modification as transition grace). Bot + release-cut PRs exempt.
+- `.gitignore` now ignores a symlinked `node_modules` too (trailing-slash patterns only match real directories).
+
+## Evidence
+
+Live bypass this detects (2026-06-05): three build worktrees created with raw `git worktree add` had no husky shim — `git commit` ran zero hooks, so a full night's worktree commits carried no decision-audit records and nothing noticed (root fixed in #829; this is the structural backstop). Pinned by `tests/unit/decision-audit-presence-check.test.ts` (9 tests: scope predicate both sides, name-status parsing incl. renames, per-entry evidence passes, legacy-grace passes, the bypass shape FAILS with the actionable husky/`npm run prepare` message, docs-only passes, bot/release exemptions). CLI self-test green on an empty diff.

package/upgrades/1.3.298.md

@@ -0,0 +1,20 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added a Gemini-specific fallback for topic sessions that finish a Telegram turn in the live pane without running the Telegram reply script. When a Gemini CLI session still has a pending Telegram injection, SessionManager now recognizes the completed final assistant block after the matching Telegram prompt and emits a detected reply once Gemini has returned to its input footer. Server wiring sends that reply back to the original Telegram topic.
+
+## What to Tell Your User
+
+Gemini topic sessions can now relay a completed final pane answer back to Telegram instead of leaving you with silence after the work finishes.
+
+## Summary of New Capabilities
+
+- Gemini final pane answers are detected and relayed for topic sessions with an unanswered Telegram message.
+
+## Evidence
+
+Live repro before the fix: Gemini topic session gemini-topic-1 showed GEMI_TASK_REPORT_1780640360 in its completed pane output, while Telegram only received the acknowledgement/status/gate messages and no final report. After the fix, focused unit coverage verifies the Gemini pane extractor and the pending-injection monitor path that clears the tracker and emits the detected reply for Telegram delivery.

package/upgrades/decision-audit-presence.eli16.md

@@ -0,0 +1,5 @@
+# A new PR check catches commits that skipped the local safety gate
+
+Every code commit in this repo is supposed to pass through a local pre-commit gate that runs lint, tier checks, and writes a small audit record of the decision. That gate is wired up by husky, a tool that activates git hooks when dependencies are installed. We discovered (the hard way, across three build folders in one night) that folders created with raw git commands never get that wiring — so commits sail through with zero local checks and no audit record, and nothing anywhere notices. CI still re-runs the big checks on the pull request, but the gate's own protections (tier floors, deferral detection, the audit trail) silently never happened.
+
+The root cause in the worktree-creation command is fixed separately. This change adds the structural backstop: a pull-request check that looks at what the PR changes. If it touches gate-scoped code (src, scripts, hooks, skills) it must ALSO carry the gate's audit record — the small decision file the gate stages into every commit it evaluates. A code PR with no record means the gate never ran for those commits, and the check fails with a message that names the likely cause (a worktree without hook wiring) and the exact fix (run `npm run prepare`, then re-commit). Docs-only PRs, bot PRs, and the automated release PR are unaffected, and PRs from before the audit-format change are accepted via their old-format record. Also fixes the `.gitignore` pattern so a symlinked `node_modules` can't be accidentally committed (a slip this very investigation made once).

package/upgrades/gemini-final-pane-relay.eli16.md

@@ -0,0 +1,9 @@
+# Gemini final pane replies now reach Telegram
+
+Gemini can finish a Telegram task by printing the final answer in its terminal pane without running the Telegram reply script. That is exactly the bad user experience: the work is visible in the live pane, but Telegram stays silent.
+
+This change gives the session monitor a Gemini-specific fallback. When a Gemini topic has an unanswered Telegram message, the monitor looks for Gemini's completed assistant block: a line beginning with `✦`, followed later by Gemini's normal input footer. Only then does it treat the block as the reply and send it to the Telegram topic.
+
+The guard is intentionally narrow. It only runs for `gemini-cli` sessions with a pending Telegram injection, only considers text after the matching `[telegram:N]` prompt, and only fires after Gemini has returned to the input/footer state. Claude and Codex keep their existing reply-script and transcript paths.
+
+Respawn-context note: after the server restart, the durable pieces survived: the Telegram history preserved the cycle id and repro, and the `gemini-final-output-relay` worktree survived cleanly. What had to be re-derived was the in-memory claim-check trail: which exact source files owned final relay, completion detection, and Gemini pane parsing.

package/upgrades/side-effects/decision-audit-presence.md

@@ -0,0 +1,47 @@
+# Side-Effects Review — decision-audit presence PR gate (task #81 close-out)
+
+**Version / slug:** `decision-audit-presence`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `self-review under the Tier-1 lite lane; over-block analysis below covers every legitimate-PR shape considered`
+
+## Summary of the change
+
+New PR-boundary check (`scripts/decision-audit-presence-check.mjs` + `.github/workflows/decision-audit-gate.yml`): a PR whose diff touches gate-scoped files (src/, scripts/, .husky/, skills/ code — the same `inScope` predicate as the pre-commit gate) must also carry gate evidence: an added `.instar/instar-dev-decisions/*.json` per-entry file (post-#827) or a modified legacy `.instar/instar-dev-decisions.jsonl` (transition grace). Otherwise it fails with an actionable message naming the husky-shim cause and the `npm run prepare` fix. Plus: `.gitignore` `node_modules/` → `node_modules` so the worktree node_modules SYMLINK is ignored too (trailing-slash patterns match only directories; the symlink slipped into a commit once tonight).
+
+## Decision-point inventory
+
+- `evaluateDecisionAuditPresence` — add — pure; exemptions mirror the eli16 PR gate (Bot authors, `chore: release` titles).
+- `isInScopeFile` — add — duplicated from `scripts/instar-dev-precommit.js` `inScope()` with a sync comment; drift only weakens detection, never blocks a PR the local gate doesn't also cover.
+- Workflow — add — `pull_request` types opened/synchronize/reopened/ready_for_review, `contents: read`, full-depth checkout for the three-dot diff.
+- `.gitignore` — modified — one-line pattern fix.
+
+## 1. Over-block analysis (can this fail a legitimate PR?)
+
+- **Docs/tests/upgrades-only PRs** — pass (no in-scope files).
+- **In-flight pre-#827 PRs** — pass via the legacy-jsonl grace path (their gate appended a line).
+- **Gated code PRs** — pass: the gate stages an audit record into every evaluated commit (post-#814), so evidence is present by construction.
+- **The genuinely-blocked shape** — in-scope changes with NO record — is exactly the bypass this exists to surface. The failure message gives the one-command fix.
+- **Bots + release-cut** — exempt, mirroring the eli16 gate.
+- **Squash-merge interaction** — none: the check runs on the PR diff (base...head), not on merged history.
+- Residual risk: an operator hand-editing in-scope files via the GitHub web UI would fail the check — correctly, since the gate never evaluated that change; the fix message applies (commit locally through the gate).
+
+## 2. Under-block
+
+Evidence is presence-based, not per-commit: one gated commit in a PR vouches for the PR even if a sibling commit bypassed. Accepted for this slice — the common failure mode (a WHOLE worktree without hooks) produces zero evidence and is caught. Per-commit matching would need trace↔commit correlation; noted as a possible tightening, not promised.
+
+## 3. Signal vs authority
+
+Deterministic file-presence check — no LLM, no semantic classification. Authority shape matches existing required CI (eli16 gate, repo invariants).
+
+## 4. Migration parity
+
+None — repo CI infrastructure, not agent-installed files.
+
+## 5. Token/cost impact
+
+One ubuntu CI job per PR event, seconds long. No LLM calls.
+
+## 6. Rollback
+
+Delete the workflow file (or revert); the script is inert without it.

package/upgrades/side-effects/gemini-final-pane-relay.md

@@ -0,0 +1,42 @@
+# Side-Effects Review — Gemini final pane Telegram relay
+
+**Version / slug:** `gemini-final-pane-relay`
+**Date:** `2026-06-05`
+**Author:** `instar-codey`
+
+## Summary
+
+When a `gemini-cli` topic session has a pending Telegram injection, `SessionManager` now checks the captured pane for a completed Gemini assistant block and emits `injectionReplyDetected`. Server wiring sends that detected reply to the same Telegram topic.
+
+## Decision-point inventory
+
+- Gemini pane parser — added — pure helper in `paneText`, requiring a `✦` assistant block followed by Gemini's idle/input footer.
+- Pending-injection monitor — modified — Gemini-only branch after liveness is confirmed and before generic completion/timeout checks.
+- Telegram send wiring — added — listens for `injectionReplyDetected` and posts to the original topic.
+
+## Direction of failure
+
+- Old failure: Gemini completed work in-pane, but no Telegram reply was sent because Gemini did not execute the relay script.
+- New behavior: a completed Gemini final block is relayed once and clears the pending injection tracker.
+- Conservative failure direction: if the pane shape is ambiguous, lacks the matching `[telegram:N]` marker, or Gemini has not returned to the idle footer, no automatic relay happens.
+
+## Side-effects checklist
+
+1. **Over-block:** The implementation relays only; it does not reject inputs or user actions. The concrete false-negative tradeoff is conservative non-relay when Gemini's footer shape changes, when the matching Telegram marker has scrolled out of the 400-line capture, or when the final block uses a shape other than the `✦` assistant marker.
+2. **Under-block:** It can still miss very long Gemini answers where the original `[telegram:N]` marker is outside the captured tail, panes with a future Gemini TUI footer vocabulary, or answers that are complete but remain in an intermediate TUI state without the idle footer.
+3. **Level-of-abstraction fit:** The helper lives in `paneText` because it is pane-shape parsing, not Telegram delivery policy. `SessionManager` owns the pending-injection tracker and can decide when a framework-specific pane observation is eligible for relay. `server` remains the Telegram transport boundary.
+4. **Signal vs authority compliance:** The parser is a detector and does not hold blocking authority. It only produces a completed-reply signal after a pending Gemini Telegram injection exists; the server listener surfaces that signal to the original topic. This complies with `docs/signal-vs-authority.md` because the brittle regex/TUI detection never blocks a judgment path.
+5. **Interactions:** The branch is scoped to `framework === 'gemini-cli'` and a live pending injection, so Claude and Codex transcript/reply-script behavior is unchanged. The pending injection is cleared before emitting the event to avoid duplicate sends on subsequent monitor ticks.
+6. **External surfaces:** Telegram users can now receive a Gemini final pane answer that previously stayed visible only in tmux. The behavior depends on runtime pane text, the pending-injection map, and Gemini's idle footer, so the implementation is intentionally narrow and fail-closed.
+7. **Rollback cost:** Reverting the parser, the Gemini monitor branch, and the server listener restores the prior behavior without data migration or state repair.
+
+## Scope not taken
+
+- No Claude/Codex behavior changes.
+- No broad "scrape any final-looking text" behavior.
+- No stale Gemini quota telemetry work; that remains parked per operator instruction.
+- No task-boundary blending fix; recorded as observation only.
+
+## Rollback
+
+Revert the parser, the Gemini pending-injection branch, and the `injectionReplyDetected` server listener. Gemini returns to the previous behavior: visible pane output may remain silent unless the agent runs the reply script.