instar 0.28.72 → 0.28.74

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-04-22T08:35:59.333Z",
-  "instarVersion": "0.28.72",
+  "generatedAt": "2026-04-25T00:12:18.203Z",
+  "instarVersion": "0.28.74",
   "entryCount": 186,
   "entries": {
     "hook:session-start": {
@@ -1112,7 +1112,7 @@
       "type": "template",
       "domain": "operations",
       "sourcePath": "src/templates/scripts/telegram-reply.sh",
-      "contentHash": "4f8787df1bf6384545dd7f19093fd77daa1bf993ed48a8ab02b6598d41a2007c",
+      "contentHash": "3d08c63c6280d0a7ba94a345c259673a461ee5c1d116cb47c95c7626c67cee23",
       "since": "2025-01-01"
     },
     "template:whatsapp-reply.sh": {
@@ -1408,7 +1408,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "07b0ed1f402436fe88c81c05aecca43d375788fdac63a832f59cdaa7c9c32e86",
+      "contentHash": "b47fdc0040c512bada61574b4fd1505da3c9bbe2adc793915d6f5bd479faad06",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {
@@ -1464,7 +1464,7 @@
       "type": "subsystem",
       "domain": "communication",
       "sourcePath": "src/lifeline/TelegramLifeline.ts",
-      "contentHash": "c9c7fd786bbab2bfefff986a3882a6267b6d5c1f2efb6a386626e65eeefc0fb8",
+      "contentHash": "22d7d3827ba85d345862e55457fd2cca83e4f38201da61e20a7f0e539052322b",
       "since": "2025-01-01"
     },
     "subsystem:orphan-process-reaper": {

package/src/templates/scripts/telegram-reply.sh

@@ -3,18 +3,52 @@
 #
 # Usage:
 #   ./telegram-reply.sh TOPIC_ID "message text"
+#   ./telegram-reply.sh --format markdown TOPIC_ID "**bold**"
 #   echo "message text" | ./telegram-reply.sh TOPIC_ID
 #   cat <<'EOF' | ./telegram-reply.sh TOPIC_ID
 #   Multi-line message here
 #   EOF
 #
+# Flags:
+#   --format <mode>   Override server-side format mode for this send.
+#                     Valid: plain, code, markdown, legacy-passthrough
+#                     ('html' is reserved for trusted internal callers.)
+#                     When absent, the server's configured default applies.
+#
 # Reads INSTAR_PORT from environment (default: 4040).
 
+FORMAT=""
+
+# Parse leading flags before positional args.
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --format)
+      FORMAT="$2"
+      shift 2
+      ;;
+    --format=*)
+      FORMAT="${1#--format=}"
+      shift
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      echo "Unknown flag: $1" >&2
+      exit 1
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
 TOPIC_ID="$1"
 shift
 
 if [ -z "$TOPIC_ID" ]; then
-  echo "Usage: telegram-reply.sh TOPIC_ID [message]" >&2
+  echo "Usage: telegram-reply.sh [--format MODE] TOPIC_ID [message]" >&2
   exit 1
 fi
 
@@ -38,22 +72,32 @@ if [ -f ".instar/config.json" ]; then
   AUTH_TOKEN=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('authToken',''))" 2>/dev/null)
 fi
 
-# Escape for JSON
-JSON_MSG=$(printf '%s' "$MSG" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))' 2>/dev/null)
-if [ -z "$JSON_MSG" ]; then
-  # Fallback if python3 not available: basic escape
-  JSON_MSG="\"$(printf '%s' "$MSG" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\n/\\n/g')\""
+# Build JSON body (text + optional format).
+JSON_BODY=$(python3 -c '
+import sys, json
+msg = sys.argv[1]
+fmt = sys.argv[2]
+body = {"text": msg}
+if fmt:
+    body["format"] = fmt
+print(json.dumps(body))
+' "$MSG" "$FORMAT" 2>/dev/null)
+
+if [ -z "$JSON_BODY" ]; then
+  # Fallback if python3 not available: basic escape, no format override.
+  ESCAPED=$(printf '%s' "$MSG" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\n/\\n/g')
+  JSON_BODY="{\"text\":\"${ESCAPED}\"}"
 fi
 
 if [ -n "$AUTH_TOKEN" ]; then
   RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/telegram/reply/${TOPIC_ID}" \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer ${AUTH_TOKEN}" \
-    -d "{\"text\":${JSON_MSG}}")
+    -d "$JSON_BODY")
 else
   RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/telegram/reply/${TOPIC_ID}" \
     -H 'Content-Type: application/json' \
-    -d "{\"text\":${JSON_MSG}}")
+    -d "$JSON_BODY")
 fi
 
 HTTP_CODE=$(echo "$RESPONSE" | tail -1)

package/upgrades/0.28.73.md

@@ -0,0 +1,33 @@
+# Upgrade Guide — v0.28.73
+
+<!-- bump: patch -->
+
+## What Changed
+
+`CapabilityMapper.classify()` now correctly labels agent-local capabilities (skills, scripts, jobs, context segments, custom hooks) that are NOT in the shipped builtin manifest and NOT linked to an evolution proposal as `user` provenance, instead of leaving them as `unknown`. The `Provenance` type has always declared `user` as a first-class value, but the classifier never assigned it — so every agent's drift report over-counted "unmapped" capabilities and `userConfigured` was always zero in the summary.
+
+Concretely, in `classify()` the final fallback checks `cap.provenance === 'unknown'` and, if so, returns the capability with `provenance: 'user'`. Non-`unknown` pre-classify provenance (e.g. the `hooks/instar/` subdir which hardcodes `instar`) is preserved untouched. The persisted `capability-manifest.json` now records `classificationReason: 'agent-local config directory'` for these entries.
+
+On the first scan after upgrading, each agent's `drift.changed` list will show a one-time provenance transition from `unknown` → `user` for every affected capability. That's expected — it's the signal that the fix took effect. `drift.unmapped` shrinks accordingly; `summary.userConfigured` populates correctly.
+
+No schema change, no API surface change, no migration required.
+
+## What to Tell Your User
+
+- **Cleaner drift reports**: "I stopped flagging my own config as mystery items. The capability map now recognizes what you and I set up together as user-authored."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Accurate user-provenance classification | Automatic on next `capability-map` scan |
+
+## Evidence
+
+Reproduction: on an agent running pre-fix, call the capability-map drift endpoint. The `unmapped` list contains every agent-local skill/script/job/context segment that isn't in the builtin manifest (~100+ entries on a mature agent). `summary.userConfigured` reads 0 even when the agent has many user-authored capabilities.
+
+After upgrading and running one scan: those entries move out of `unmapped` and into the `user`-provenance tally. `drift.changed` shows the one-time transition for each affected capability.
+
+Unit-level verification: `tests/unit/capability-mapper-advanced.test.ts` "classifies unmatched agent-local capabilities as user (not unmapped)" asserts both that a mystery skill is NOT in `drift.unmapped` and that its `provenance` on the capability map equals `'user'`. All 208 tests across the three capability-mapper test files pass.
+
+Reporter: `cluster-capability-map-has-104-unmapped-capabilities` (2 reports, governance=implement).

package/upgrades/0.28.74.md

@@ -0,0 +1,48 @@
+# Upgrade Guide — v0.28.74
+
+<!-- bump: patch -->
+
+## What Changed
+
+The scope-coherence stop hook (`scope-coherence-checkpoint.js`) previously
+suggested running `/grounding` as the only recovery path when the
+implementation-depth threshold was crossed. `/grounding` is a Claude-Code-side
+skill convention; Instar does not ship it, so agents whose harness lacks that
+skill saw a dead-end suggestion with no working manual reset path.
+
+The checkpoint message now lists three real options: read the relevant
+spec/proposal, invoke `/grounding` if the harness has it, or reset directly via
+the local Instar server's reset endpoint. The endpoint already exists and is
+what `session-start.sh` invokes automatically — this release just surfaces it
+as a manual fallback in the message agents see when they hit the checkpoint.
+
+No code paths changed beyond the human-readable message string. The reset
+endpoint and the depth-accumulation logic are unchanged.
+
+## What to Tell Your User
+
+- The scope-coherence checkpoint now points to a manual reset path that always works, so if the suggested skill is not installed in your setup you still have a one-line recovery I can run for you.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Manual scope-coherence reset surfaced in checkpoint message | `curl -X POST http://localhost:4040/scope-coherence/reset` |
+
+## Evidence
+
+Cluster `cluster-scope-coherence-hook-counter-never-resets-across-sessions`
+flagged that `/grounding` is not a registered skill or command in Instar and
+that there is no user-facing reset path shown in the checkpoint message.
+
+Verification: `ls skills/` confirms no `grounding` skill ships with Instar.
+The reset endpoint is implemented at `src/server/routes.ts:2925` and is
+invoked by `.instar/hooks/instar/session-start.sh` when the local server is
+healthy — so the underlying counter reset already works on every session
+start; this release makes the manual fallback path discoverable from the
+hook's own message.
+
+Reproduction: trigger the checkpoint (implementation depth ≥ 20, cooldown
+elapsed, server running) and inspect the `reason` field in the hook's
+output. Before: ends with `or /grounding`. After: ends with the three-option
+block including the explicit curl command for manual reset.

package/upgrades/side-effects/0.28.73.md

@@ -0,0 +1,80 @@
+# Side-Effects Review — Capability Map user-provenance fallback
+
+**Version / slug:** `capability-map-user-provenance-fallback`
+**Date:** `2026-04-22`
+**Author:** Dawn (instar-bug-fix autonomous job, AUT-6010-wo)
+**Second-pass reviewer:** not-required (LOW-risk classifier fallback; no public API, schema, or adapter surface touched)
+
+## Summary of the change
+
+In `src/core/CapabilityMapper.ts`, the `classify()` method now assigns `provenance: 'user'` to any capability that falls through all three existing classification rules (builtin-manifest, evolution linkage, custom hook dir) AND still carries the pre-classify default `'unknown'`. Capabilities whose scanners pre-assign a non-`unknown` provenance (e.g. the `hooks/instar/` subdir) are preserved untouched.
+
+The persisted manifest's `classificationReason` gains a matching case: `'agent-local config directory'` for `user`-classified entries.
+
+Files touched:
+- `src/core/CapabilityMapper.ts` — two edits in the `classify()` and `persistManifest()` methods.
+- `tests/unit/capability-mapper-advanced.test.ts` — one existing test renamed and updated to assert the new behavior (mystery skill classified as `user`, not left in `drift.unmapped`).
+
+Feedback cluster addressed: `cluster-capability-map-has-104-unmapped-capabilities`. Reporter wanted the drift endpoint to stop flagging fully-functional agent-local capabilities as "unmapped." This ships exactly that: agent-local skills/scripts/jobs/context that aren't shipped-builtin and aren't evolution-linked are now correctly labeled `user`-provenance.
+
+## Decision-point inventory
+
+- Final fallback branch in `classify()` — **modify** — converts `unknown` → `user` when nothing else matched; preserves non-`unknown` pre-set provenance.
+- `classificationReason` ternary in `persistManifest()` — **extend** — new case `user ? 'agent-local config directory'`.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+None. The change adds a positive classification where one was missing. It does not gate, reject, or short-circuit any path. The only capabilities affected are those that previously would have been labeled `unknown`; they now get a more specific `user` label.
+
+Hooks already pre-assigned `instar` by the scanner (`hooks/instar/` subdir) would be overwritten by a naive fallback, so the guard `cap.provenance === 'unknown'` explicitly preserves them.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- Capabilities legitimately sourced from neither the bundle, an evolution proposal, nor the agent's own config — e.g. a third-party drop-in dir if one ever exists — would also be labeled `user`. Today no such source exists; the scanners only reach paths under `projectDir/.claude/` and `stateDir/hooks/`, both agent-owned. If a future scanner adds a truly "external" source, it must pre-assign a non-`unknown` provenance to avoid mislabeling.
+- Already-persisted `unknown` entries in each agent's on-disk `capability-manifest.json` will continue to show `unknown` until the next `refresh()` runs. That's fine: drift detection already re-classifies on scan; no migration is required.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The classifier is the correct seam — it's the single chokepoint every capability passes through, and the `Provenance` type already names `'user'` as a first-class value. The alternative (adding `user` at each scanner) would duplicate the rule across six scanners and drift over time. The alternative (post-hoc in `buildMap`) would scatter classification across multiple layers.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** `docs/signal-vs-authority.md`
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No. This change has zero blocking authority. It produces a *label* on a read-only classification path. No gating, no rejection, no downstream authority decision hangs off the new label; the drift endpoint and summary table consume the label for display only.
+
+---
+
+## 5. Interactions
+
+- **Manifest persistence** — the new label is written to `capability-manifest.json`. Persisted entries that previously read `provenance: 'unknown'` will, on the next scan, persist as `provenance: 'user'`. The drift detector's `changed` list will surface these as a one-time provenance transition per agent. That's expected and visible in the drift report; it's the signal that the fix took effect.
+- **Summary counters** — `buildMap()` already counts `user`-provenance capabilities into `userConfigured`. That counter was 0 for all agents pre-fix; it now reflects reality. `unmapped` drops correspondingly.
+- **Test coupling** — one existing test (`reports unmapped capabilities (unknown provenance)`) asserted the old behavior and has been renamed and updated. All 208 tests across the three capability-mapper test files still pass.
+
+---
+
+## 6. Revert cost
+
+Single-commit revert. Two tiny edits in `CapabilityMapper.ts` plus one test update. No schema, migration, config, or API contract changed. Persisted manifests with `user` provenance would be re-labeled `unknown` on the next post-revert scan — fully reversible.
+
+---
+
+## 7. Justification for shipping now (vs. deferring)
+
+The cluster has sat with governance=`implement` and concrete research notes pointing at the exact line of code. The fix is two small conditional edits; the risk of shipping is strictly lower than the continued noise of ~100+ agent-local capabilities being flagged as "unmapped" across every drift report on every agent. Deferring would keep the drift signal polluted and continue to show `userConfigured: 0` in summaries that should show a much larger number.

package/upgrades/side-effects/telegram-markdown-renderer-pr1.md

@@ -0,0 +1,124 @@
+# Side-Effects Review — Telegram markdown renderer (PR1: formatter module, disabled)
+
+**Version / slug:** `telegram-markdown-renderer-pr1`
+**Date:** `2026-04-24`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (no block/allow surface, no wiring into send paths, shipped disabled)`
+
+## Summary of the change
+
+PR1 of the two-PR plan in `docs/specs/TELEGRAM-MARKDOWN-RENDERER-SPEC.md` (approved 2026-04-24 by Justin via Telegram topic 8183). Adds a new pure-function module `src/messaging/TelegramMarkdownFormatter.ts` that ports Dawn's `telegram_format.py` (the-portal) to TypeScript, plus a Vitest test suite `tests/unit/telegram-markdown-formatter.test.ts` with 105 passing tests.
+
+The module exports `formatForTelegram(text, mode)`, `format(text, mode)`, `lintTelegramMarkdown(text)`, and primitives (`escapeHtmlText`, `escapeHtmlAttribute`, `isSafeUrl`). It implements the spec's full 12-step markdown→Telegram-HTML pipeline, a balanced-paren URL scanner (Wikipedia-style parens), WHATWG URL scheme allowlist, distinct HTML-text vs HTML-attribute escapers, NUL + Supplementary-PUA-B stripping for sentinel-collision safety, a 32KB input guard that falls back to plain mode without byte loss (`conversionSkipped: true`), and a `legacy-passthrough` mode that returns input byte-for-byte unchanged with `parseMode: undefined` so callers retain their historical `parse_mode`.
+
+**Critically, no send path is wired to this module.** `TelegramAdapter.ts` and `TelegramLifeline.ts` are untouched. The module is dead code at runtime until PR2 wires `apiCall()` behind the `telegramFormatMode` config accessor. PR2 ships with `legacy-passthrough` as the default, so PR1 has zero behavioral effect on any agent even after PR2 merges.
+
+## Decision-point inventory
+
+This PR contains no runtime decision points — the module is not called by anything. The future decision points it enables (documented here for completeness; all are PR2 scope):
+
+- `TelegramAdapter.apiCall` — formatter invocation conditional on `method === 'sendMessage' || method === 'editMessageText'`. **Not in this PR.**
+- `TelegramLifeline.apiCall` — same. **Not in this PR.**
+- Trusted-internal-caller allowlist for `html` mode. **Not in this PR.**
+
+Decision points inside the module itself (pure functions, no runtime authority):
+
+- `isSafeUrl(raw)` — scheme allowlist (http/https/tg/mailto). Pure function; refuses unsafe schemes by returning `null`. Caller decides what to do with the rejection (emit literal text).
+- `lintTelegramMarkdown(text)` — pure detector returning string array. Advisory-only; no blocking authority in this PR.
+- 32KB length guard in `formatForTelegram` — falls back to plain mode on oversized input. Pure transformation; no network/storage side effect.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface in PR1 — module is not wired. Future-facing concerns the module itself introduces:
+
+- `legacy-passthrough` mode emits no lint issues (by design — it's the rollback target and must be behaviorally identical to pre-cutover). A future operator might want lint-as-observation in passthrough mode; noted as open question for PR2.
+- `isSafeUrl` rejects `javascript:`, `data:`, `file:`, `vbscript:`, and any non-allowlisted scheme. Rejected links become literal text (`[click](javascript:...)` rendered verbatim) — a legitimate agent-authored `tg://resolve?domain=foo` link is permitted (mode allowed). Wikipedia-style `https://...wiki/X_(y)` URLs parse correctly via the balanced-paren scanner (covered by fixture test).
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+No block/allow surface in PR1. Module-internal known gaps (documented in spec, accepted as v1):
+
+- Italic between emoji (`🎉*bold*🎉`) renders literal asterisks because the punctuation-class lookaround doesn't include emoji — accepted v1 per spec iteration-2 L4.
+- `tg://` deep links are permitted (spec allowlists them); future spec may tighten.
+- PUA-B range is stripped from input before sentinels are inserted — this means a user message legitimately containing PUA-B codepoints will lose those bytes. Near-zero real-world usage; accepted trade-off per spec. Not flagged as `truncated` because "byte loss" in the spec is reserved for the oversized-`<pre>` fallback.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The module is a pure string-transform library at the same layer as `MessageFormatter.ts`. It owns no I/O, no config reading, no network, no logging. It does not hold blocking authority. The decision "should this send happen at all?" stays with the adapter/lifeline chokepoints; the formatter only answers "given this text and mode, what bytes go on the wire?"
+
+This is consistent with the spec's architectural intent: the formatter is a detector+transformer producing `{ text, parseMode, lintIssues }`, consumed downstream by the adapter which holds the authoritative send/no-send decision.
+
+---
+
+## 4. Signal vs authority compliance
+
+Per `docs/signal-vs-authority.md`:
+
+- **Lint is a signal, not an authority.** `lintTelegramMarkdown` returns canonical prose-string issues. It does not reject a send. The spec specifies lint-strict mode (which a downstream authority can consume to return 422) as PR2 scope; PR1's lint is purely observational.
+- **Scheme allowlist is a deterministic transform, not a policy decision.** `isSafeUrl` is brittle-by-design (WHATWG URL + scheme set). It does not block a send — it causes a link to render as literal text. The outbound send still happens. This satisfies the "brittle logic must not hold blocking authority" rule: brittle logic (regex/parse) produces a transformation, not a decision to refuse a user action.
+- **No sentinel, gate, watchdog, or sentinel-class name is introduced by this PR.**
+
+Compliance: PASS.
+
+---
+
+## 5. Interactions
+
+- No shadow/shadowed interactions in PR1 — module is not called by anything. Search confirms no existing import site.
+- Module name collision check: `src/messaging/` contains `MessageFormatter.ts` (different purpose: envelope formatting) and no `TelegramMarkdownFormatter.ts` prior to this PR. No collision.
+- Test file name: `tests/unit/telegram-markdown-formatter.test.ts`. No existing test file of that name.
+- PR2 will introduce interactions with `TelegramAdapter.apiCall`, `TelegramLifeline.apiCall`, `MessageStore` (raw/sent fields), and `GitSyncTransport` (envelope flag). Those interactions get their own artifact at PR2 time.
+
+---
+
+## 6. External surfaces
+
+**Does it change anything visible to other agents, other users, other systems?**
+
+No. PR1 ships dead code. No route changes, no message format changes on the wire, no config schema changes applied (config fields `telegramFormatMode` / `telegramLintStrict` are spec'd but deliberately not added in PR1 — they land in PR2 alongside the wiring), no database changes, no envelope changes.
+
+- Bot API: untouched — adapter still sends exactly the bytes it sends today with exactly the `parse_mode` it uses today.
+- MessageStore: untouched.
+- GitSyncTransport: untouched.
+- Shell-script `.claude/scripts/telegram-reply.sh`: untouched.
+- Agent dashboards / self-knowledge: untouched.
+
+No timing dependencies, no conversation state dependencies.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Trivial. PR1 is a code-only addition with no runtime invocation. Rollback options in order of cost:
+
+1. **Do nothing.** The module is not on any call path; a latent bug is invisible until PR2.
+2. **Revert the merge commit.** Standard `git revert` — affects only two new files. No data migration, no agent state repair, no config flip.
+3. **Fix forward.** The module is pure functions with 105 unit tests; most fixes ship as deltas.
+
+PR2 itself is governed by the spec's staged-rollout (ships with `legacy-passthrough` default; canary via config flip). That's PR2's rollback story — out of scope for this artifact.
+
+---
+
+## Second-pass review
+
+Not required. PR1 has no block/allow surface, no session-lifecycle surface, no sentinel/gate/watchdog, no coherence/idempotency/trust change, and is shipped disabled. High-risk criteria from Phase 5 are not met.
+
+## Spec linkage
+
+- Approved spec: `docs/specs/TELEGRAM-MARKDOWN-RENDERER-SPEC.md` (approved 2026-04-24T20:53:47Z by Justin via Telegram topic 8183).
+- Convergence report: `docs/specs/reports/telegram-markdown-renderer-convergence.md`.
+- Dawn reference impl: `the-portal/.claude/scripts/telegram_format.py` (merged 2026-04-24T17:57Z).