instar 1.3.1036 → 1.3.1037

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "b75c147afd1f5a9843ca4eac372159f3623f24731fe63b2f59e48043ae488af9",
   "articleCount": 82,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1036"
+  "packageVersion": "1.3.1037"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1036",
+  "version": "1.3.1037",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/skills/spec-converge/scripts/publish-spec-review.mjs

@@ -33,6 +33,56 @@ import { checkEli16Overview } from '../../../scripts/eli16-overview-check.mjs';
 
 export const API_PORT = Number(process.env.INSTAR_PORT) || 4042;
 
+/** Relay locations, in resolution order (the second is the documented older-install path). */
+const RELAY_RELATIVE_PATHS = ['.instar/scripts/telegram-reply.sh', '.claude/scripts/telegram-reply.sh'];
+
+/**
+ * Locate telegram-reply.sh by walking UP from `startDir`.
+ *
+ * It used to be spawned as the bare relative path `.instar/scripts/telegram-reply.sh`,
+ * which only resolves when cwd IS the agent home. instar-dev work is REQUIRED to happen
+ * in a worktree (docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md), and a worktree has no
+ * `.instar/scripts/`, so every send from one failed with ENOENT. Walking up from a
+ * worktree at `<agent-home>/.worktrees/<slug>` reaches `<agent-home>`, which has it.
+ *
+ * Returns an absolute path, or null when no relay exists above `startDir`.
+ */
+export function resolveRelayScript(startDir = process.cwd(), existsSync = fs.existsSync) {
+  const envHome = process.env.INSTAR_AGENT_HOME;
+  const roots = [];
+  if (envHome) roots.push(path.resolve(envHome));
+  let dir = path.resolve(startDir);
+  for (;;) {
+    roots.push(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  for (const root of roots) {
+    for (const rel of RELAY_RELATIVE_PATHS) {
+      const candidate = path.join(root, rel);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Did the relay actually deliver?
+ *
+ * The relay prints `Sent <n> chars to topic <id>` on a real send. Requiring that
+ * marker — not merely a zero exit — is deliberate: this script's whole job is
+ * handing the operator something to approve, and it previously printed
+ * "[published] … delivered" straight after an ENOENT, so a dropped approval ask
+ * was indistinguishable from a delivered one. Filed three times in fifteen days
+ * (ACT-616 2026-07-13, ACT-1390 2026-07-27, ACT-1517 2026-07-28) before this fix.
+ */
+export function relayDelivered(result) {
+  if (!result || result.error) return false;
+  if (result.status !== 0) return false;
+  return /Sent\s+\d+\s+chars?\s+to\s+topic/i.test(`${result.stdout || ''}${result.stderr || ''}`);
+}
+
 /** Split a spec file into its frontmatter body and the rest. */
 export function extractFrontmatter(specText) {
   const m = specText.match(/^---\n([\s\S]*?)\n---/);
@@ -144,11 +194,30 @@ async function main() {
       console.error('--send requires --topic <id>');
       process.exit(2);
     }
-    const reply = spawnSync('bash', ['.instar/scripts/telegram-reply.sh', String(args.topic)], {
+    const relay = resolveRelayScript();
+    if (!relay) {
+      console.error(
+        'REFUSING to claim delivery: no telegram-reply.sh found at or above this directory ' +
+        `(looked for ${RELAY_RELATIVE_PATHS.join(' / ')}). The spec was NOT sent.`,
+      );
+      console.error('The composed message follows so the ask is not lost — send it yourself.');
+      console.log(message);
+      process.exit(1);
+    }
+    const reply = spawnSync('bash', [relay, String(args.topic)], {
       input: message, encoding: 'utf8',
     });
     process.stderr.write(reply.stdout || '');
     process.stderr.write(reply.stderr || '');
+    if (!relayDelivered(reply)) {
+      const why = reply.error
+        ? reply.error.message
+        : `relay exited ${reply.status} without a send confirmation`;
+      console.error(`\n[NOT DELIVERED] the spec was NOT sent to topic ${args.topic}: ${why}`);
+      console.error('The composed message follows so the ask is not lost — send it yourself.');
+      console.log(message);
+      process.exit(1);
+    }
     console.error(`\n[published] ELI16 link verified (HTTP 200) and delivered to topic ${args.topic}.`);
   } else {
     // Print the message + the verified link for the caller to send.

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-28T18:31:33.781Z",
-  "instarVersion": "1.3.1036",
+  "generatedAt": "2026-07-28T18:42:16.061Z",
+  "instarVersion": "1.3.1037",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "b75c147afd1f5a9843ca4eac372159f3623f24731fe63b2f59e48043ae488af9",
   "articleCount": 82,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1036"
+  "packageVersion": "1.3.1037"
 }

package/upgrades/1.3.1037.md

@@ -0,0 +1,53 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`skills/spec-converge/scripts/publish-spec-review.mjs` spawned the relay script as a bare
+relative path (`.instar/scripts/telegram-reply.sh`) and then printed
+`[published] … delivered to topic N` without inspecting the spawn result.
+
+instar-dev work is required to happen in a worktree, and a worktree has no
+`.instar/scripts/`, so every send from one failed with ENOENT and was reported as
+delivered. Reproduced live: the ENOENT line and the "delivered" line printed one after the
+other, and the operator received nothing.
+
+This matters because the script sits on a hook-enforced path — `grounding-before-messaging`
+blocks a hand-written spec-review message and directs the agent here — so the one tool
+whose job is delivering approval asks could silently drop them, leaving work "awaiting
+operator approval" that the operator was never actually asked for.
+
+Two changes:
+
+- `resolveRelayScript()` walks up from cwd until it finds the relay, so a worktree reaches
+  the agent home. Honors `INSTAR_AGENT_HOME` first and falls back to the documented
+  `.claude/scripts/` path for older installs. Returns null rather than a guessed path.
+- `relayDelivered()` requires the relay's own `Sent <n> chars to topic <id>` confirmation,
+  not merely exit 0. On any failure the script prints `[NOT DELIVERED]` with the reason,
+  emits the composed message so the ask is not lost, and exits 1 — it fails closed instead
+  of failing silent.
+
+The script already refused a broken link, a missing overview, and a stub overview — and
+then did not check whether the message sent. Filed three times in fifteen days (ACT-616
+2026-07-13, ACT-1390 2026-07-27, ACT-1517 2026-07-28) before being fixed.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- 11 unit tests over both exported functions, including the exact production failure
+  (ENOENT → not delivered), the worktree walk-up that shipped broken, the `.claude`
+  fallback, precedence when both exist, and exit-0-with-no-confirmation.
+- Proven against the real filesystem from the actual worktree: `resolveRelayScript`
+  returns the agent home's relay and it exists on disk.
+- The fix direction was confirmed before the code was written — the unmodified script run
+  from the agent home printed `Sent 408 chars to topic 29723` and genuinely delivered,
+  while the same command from the worktree printed ENOENT followed by "delivered".

package/upgrades/side-effects/publish-spec-review-honest-send.md

@@ -0,0 +1,96 @@
+# Side-effects review — publish-spec-review honest send
+
+**Change.** `publish-spec-review.mjs` spawned `.instar/scripts/telegram-reply.sh` as a
+bare relative path and then printed `[published] … delivered to topic N` without
+inspecting the spawn result. Now the relay is resolved by walking up from cwd (with the
+documented `.claude/scripts/` fallback), and delivery is only claimed when the relay's own
+`Sent <n> chars to topic <id>` confirmation is present.
+
+**This bug was filed three times in fifteen days before being fixed:** ACT-616
+(2026-07-13, medium), ACT-1390 (2026-07-27, high), ACT-1517 (2026-07-28, high).
+Reproduced live at 18:09Z: the ENOENT line and the "delivered" line printed one after the
+other, and the operator received nothing.
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+The delivery check requires the relay's `Sent … chars to topic …` marker, so a future
+relay that succeeds *silently* would be reported as NOT delivered — a false negative.
+Accepted deliberately: this script's only job is handing the operator something to
+approve, so a false "didn't send" (which prints the composed message for manual sending
+and exits 1) is strictly safer than a false "sent". If the relay's output contract
+changes, this test fails loudly rather than the ask disappearing quietly.
+
+The path walk can in principle find a relay in an unrelated ancestor directory. In the
+agent-home/worktree layout the first match walking up is the agent's own relay, and
+`INSTAR_AGENT_HOME` takes precedence when set.
+
+## 2. Under-block — what failure modes does this still miss?
+
+- **The relay can confirm a send that Telegram later drops.** `Sent N chars` means the
+  relay accepted and posted it; downstream delivery failure is the relay's own retry
+  domain (PendingRelayStore / DeliveryFailureSentinel), not this script's.
+- **A wrong topic id still "delivers"** — to the wrong place. Not addressed here.
+- **Non-`--send` callers are unchanged**: they print the message and the verified link for
+  the caller to send, and can still drop it themselves. That path already exits 0
+  honestly because it never claims delivery.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. "Where does the relay live" is knowledge the spawning process must have,
+and "did the spawn work" is a question only the spawner can ask. Neither belongs to the
+relay or the caller. The walk-up specifically encodes the worktree convention
+(`docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md`), which is *why* cwd is reliably not the
+agent home.
+
+## 4. Signal vs authority compliance
+
+Compliant, and this is the crux. The script sits on a hook-ENFORCED path: the
+`grounding-before-messaging` hook BLOCKS a hand-written spec-review message and directs
+the agent here. So this script holds real authority over whether an operator ever sees an
+approval ask — and it was reporting success without checking. A brittle, unchecked step
+was granted the last word on a human decision point.
+
+The fix adds no new blocking authority. It makes an existing authority *honest*: it now
+fails closed (exit 1, message printed for manual sending) instead of failing silent.
+
+## 5. Interactions
+
+- **The grounding hook** is the upstream producer of traffic here; unchanged.
+- **telegram-reply.sh** is spawned identically, only via an absolute resolved path. Its
+  own duplicate-suppression and tone-gate behaviour are untouched.
+- **No double-send risk:** the delivery check is read-only on the result; it never retries.
+  A false negative prints the message for a human to send, which could produce a duplicate
+  if the relay *had* silently sent it — bounded by the relay's own exact-duplicate
+  suppression window.
+- No shadowing, no race: one synchronous spawn, one verdict.
+
+## 6. External surfaces
+
+Developer/agent tooling under `skills/`. No runtime agent behaviour, route, config, job,
+message schema, or persisted state changes. The only externally visible difference is that
+a failed send is now reported as failed — previously it was reported as success.
+
+## 7. Multi-machine posture
+
+**Machine-local BY DESIGN.** The question answered is "where on THIS disk is this agent's
+relay script" — a per-machine filesystem fact. Replicating or proxying it would be
+incorrect; a peer's relay path says nothing about this machine's. No durable state, no
+generated URL, no user-facing notice, so nothing strands on a topic transfer. The rendered
+private-view link the script produces is a separate concern and already tunnel-backed.
+
+## 8. Rollback cost
+
+Revert the commit. Two pure exported functions and one call site; no persisted state, no
+migration, no config. Reverting restores the false-success behaviour, which is the reason
+not to.
+
+## Verification
+
+- 11 unit tests over both exported functions, including the exact production failure
+  (ENOENT → `relayDelivered` false) and the worktree walk-up that shipped broken.
+- Proven against the real filesystem from the actual worktree: `resolveRelayScript`
+  returns the agent home's relay and `fs.existsSync` on it is true.
+- The end-to-end fix direction was confirmed before writing the code — running the
+  unmodified script from the agent home printed `Sent 408 chars to topic 29723` and
+  genuinely delivered, while running it from the worktree printed ENOENT followed by
+  "delivered".