instar 1.3.81 → 1.3.83

package/src/templates/scripts/convergence-check.sh

@@ -59,36 +59,54 @@ fi
 # Known-safe domains are whitelisted; anything else gets flagged.
 URLS_IN_MSG=$(echo "$CONTENT" | grep -oE 'https?://[^ )"'"'"'>]+' 2>/dev/null || true)
 if [ -n "$URLS_IN_MSG" ]; then
-  # The agent's OWN tunnel domain is trusted — a private-view / dashboard link
-  # the agent just generated via POST /view is not a confabulation. Read the
-  # live tunnel host from the persisted tunnel state so custom-domain tunnels
-  # are covered too (not just the default *.dawn-tunnel.dev / *.trycloudflare.com).
+  # The agent's OWN configured tunnel hostname is trusted — a private-view,
+  # dashboard, or Secret Drop link generated by this agent is not a
+  # confabulation. Read it from config at runtime. If config/python is
+  # unavailable or tunnel.hostname is empty, fall back to the static allowlist.
   OWN_TUNNEL_HOST=""
-  for tj in "${CLAUDE_PROJECT_DIR:-.}/.instar/state/tunnel.json" "${CLAUDE_PROJECT_DIR:-.}/.instar/tunnel.json"; do
-    if [ -f "$tj" ]; then
-      OWN_TUNNEL_HOST=$(python3 -c "
-import json,sys,re
+  CONFIG_PATH="${CLAUDE_PROJECT_DIR:-.}/.instar/config.json"
+  if [ -f "$CONFIG_PATH" ]; then
+    OWN_TUNNEL_HOST=$(python3 - "$CONFIG_PATH" <<'PY' 2>/dev/null
+import json
+import sys
+from urllib.parse import urlparse
+
 try:
-    d=json.load(open('$tj'))
-    u=d.get('url') or d.get('tunnelUrl') or ''
-    m=re.search(r'https?://([^/]+)', u)
-    print(re.escape(m.group(1)) if m else '')
+    cfg = json.load(open(sys.argv[1]))
+    raw = ((cfg.get('tunnel') or {}).get('hostname') or '').strip()
+    if not raw:
+        print('')
+    else:
+        parsed = urlparse(raw if '://' in raw else f'https://{raw}')
+        print((parsed.hostname or '').lower())
 except Exception:
     print('')
-" 2>/dev/null)
-      [ -n "$OWN_TUNNEL_HOST" ] && break
-    fi
-  done
+PY
+)
+  fi
 
   UNFAMILIAR_URLS=""
   while IFS= read -r url; do
     [ -z "$url" ] && continue
-    # Skip the agent's own live tunnel host (dynamic, covers custom domains).
-    if [ -n "$OWN_TUNNEL_HOST" ] && echo "$url" | grep -qE "$OWN_TUNNEL_HOST"; then
+    URL_HOST=$(python3 - "$url" <<'PY' 2>/dev/null
+import sys
+from urllib.parse import urlparse
+try:
+    print((urlparse(sys.argv[1]).hostname or '').lower())
+except Exception:
+    print('')
+PY
+)
+    # Skip the agent's own configured tunnel host.
+    if [ -n "$OWN_TUNNEL_HOST" ] && [ "$URL_HOST" = "$OWN_TUNNEL_HOST" ]; then
+      continue
+    fi
+    # Skip Cloudflare quick-tunnel hosts. These are ephemeral but agent-generated.
+    if echo "$URL_HOST" | grep -qE '(^|\.)trycloudflare\.com$'; then
       continue
     fi
     # Skip well-known service domains + common agent tunnel domains.
-    if echo "$url" | grep -qE '(github\.com|vercel\.app|vercel\.com|netlify\.app|netlify\.com|npmjs\.com|npmjs\.org|cloudflare\.com|google\.com|twitter\.com|x\.com|youtube\.com|reddit\.com|discord\.com|discord\.gg|telegram\.org|t\.me|localhost|127\.0\.0\.1|stackoverflow\.com|developer\.mozilla\.org|docs\.anthropic\.com|anthropic\.com|openai\.com|claude\.ai|notion\.so|linear\.app|fly\.io|render\.com|railway\.app|heroku\.com|amazonaws\.com|azure\.com|gitlab\.com|bitbucket\.org|docker\.com|hub\.docker\.com|pypi\.org|crates\.io|rubygems\.org|pkg\.go\.dev|wikipedia\.org|medium\.com|substack\.com|circle\.so|ghost\.io|telegraph\.ph|dawn-tunnel\.dev|trycloudflare\.com)'; then
+    if echo "$url" | grep -qE '(github\.com|vercel\.app|vercel\.com|netlify\.app|netlify\.com|npmjs\.com|npmjs\.org|cloudflare\.com|google\.com|twitter\.com|x\.com|youtube\.com|reddit\.com|discord\.com|discord\.gg|telegram\.org|t\.me|localhost|127\.0\.0\.1|stackoverflow\.com|developer\.mozilla\.org|docs\.anthropic\.com|anthropic\.com|openai\.com|claude\.ai|notion\.so|linear\.app|fly\.io|render\.com|railway\.app|heroku\.com|amazonaws\.com|azure\.com|gitlab\.com|bitbucket\.org|docker\.com|hub\.docker\.com|pypi\.org|crates\.io|rubygems\.org|pkg\.go\.dev|wikipedia\.org|medium\.com|substack\.com|circle\.so|ghost\.io|telegraph\.ph)'; then
       continue
     fi
     UNFAMILIAR_URLS="$UNFAMILIAR_URLS  $url\n"

package/upgrades/1.3.82.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+The pre-message URL provenance check now recognizes the agent's own configured tunnel hostname and Cloudflare quick-tunnel hosts. This fixes a Secret Drop dogfood failure where the agent generated a legitimate one-time collection link, but the convergence check treated the tunnel URL as an unfamiliar fabricated domain. The fix also covers private-view links served over the same tunnel path. Random unfamiliar domains still flag.
+
+## What to Tell Your User
+
+I can now send my own Secret Drop and private-view links through the normal chat path without the pre-message URL check mistaking them for made-up outside links.
+
+## Summary of New Capabilities
+
+| Area | Capability |
+| --- | --- |
+| Secret Drop | One-time links served on the agent's own tunnel pass the pre-message URL provenance check. |
+| Private views | Agent-generated view links on the configured tunnel no longer trip the fabricated-URL guard. |
+| Message safety | Random unfamiliar domains still flag, and missing config falls back to the existing conservative behavior. |
+
+## Evidence
+
+- Unit coverage: `tests/unit/convergence-check.test.ts` verifies configured tunnel URLs and Cloudflare quick-tunnel URLs pass, while random fabricated domains still raise URL provenance warnings when config is missing.

package/upgrades/1.3.83.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Project Map now includes a concise related-worktrees section when an agent has source worktrees in its conventional workspace. This fixes a dogfood issue where Codey's map was technically fresh and accurate for the small wrapper project, but omitted the Instar source worktrees where the real development work was happening. The headline file count also now skips hidden state/worktree directories consistently with the visible directory breakdown, so aged agents with large transcript/state folders do not get noisy inflated totals.
+
+## What to Tell Your User
+
+Project Map now gives me better spatial awareness when I’m developing through nearby source worktrees, and its headline file count is less likely to be inflated by hidden runtime state.
+
+## Summary of New Capabilities
+
+| Area | Capability |
+| --- | --- |
+| Project Map | Compact and markdown maps can show related agent worktrees when they exist. |
+| Spatial awareness | Development agents can see nearby source worktrees without scanning the whole machine. |
+| Count accuracy | Hidden state and worktree directories no longer inflate the headline project file count. |
+| Refresh safety | Agents without related worktrees keep the existing compact map behavior. |
+
+## Evidence
+
+- Unit coverage: `tests/unit/ProjectMapper.test.ts` verifies related worktree discovery and compact/markdown rendering.
+- Integration coverage: `tests/integration/coherence-routes.test.ts` verifies the Project Map API routes still serve JSON, markdown, compact, and refresh responses.

package/upgrades/side-effects/convergence-check-own-tunnel-url.md

@@ -0,0 +1,82 @@
+# Side-Effects Review — Convergence Check Own Tunnel URL Allowlist
+
+**Version / slug:** `convergence-check-own-tunnel-url`
+**Date:** `2026-05-29`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required by tooling`
+
+## Summary of the change
+
+This change updates the shipped `convergence-check.sh` template so URL provenance accepts the agent's own configured tunnel hostname and Cloudflare quick-tunnel hosts while preserving unfamiliar-domain blocking. It adds unit coverage in `tests/unit/convergence-check.test.ts` for configured tunnel URLs, quick-tunnel URLs, and missing-config fallback.
+
+## Decision-point inventory
+
+- `convergence-check.sh` URL provenance check — modify — deterministic pre-message quality gate deciding whether a URL host is familiar enough to send without warning.
+
+---
+
+## 1. Over-block
+
+This reduces the observed over-block where self-generated Secret Drop and private-view links on the agent's tunnel were classified as fabricated. Remaining over-block: if an agent serves a user-facing link through a tunnel hostname that is not in config and is not a Cloudflare quick-tunnel hostname, the check may still flag it.
+
+---
+
+## 2. Under-block
+
+The under-block risk is allowing a bad URL on the agent's own configured tunnel host. That risk is bounded because the hostname belongs to the agent's server, and the path still points back to this agent rather than an arbitrary external domain. A random unfamiliar domain still flags.
+
+---
+
+## 3. Level-of-abstraction fit
+
+This is a deterministic structural check over URL host provenance, so the shell pre-message gate is the right layer. It does not try to judge message meaning; it only distinguishes known host classes from unknown host classes.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no conversational block/allow surface.
+
+This is a hard provenance invariant, not a semantic judgment. The check stays narrow and deterministic: exact configured host, loopback, known public domains, and Cloudflare quick-tunnel hosts.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** This runs before the server-side tone gate. It only prevents false URL-provenance blocks before the message reaches the tone gate.
+- **Double-fire:** No double action. The convergence check either passes or reports a warning; normal message delivery then proceeds.
+- **Races:** The script reads config at send time. If the config is temporarily absent or malformed, it falls back to existing behavior.
+- **Feedback loops:** Positive loop: agents can use Secret Drop and private views instead of less safe credential or report-sharing workarounds.
+
+---
+
+## 6. External surfaces
+
+Users can receive self-generated tunnel links for Secret Drop and private views through the normal messaging path. Other unfamiliar URLs are unchanged and still flagged. Existing agents receive the fix because PostUpdateMigrator overwrites the convergence-check template during migration.
+
+---
+
+## 7. Rollback cost
+
+Rollback is a normal hot-fix revert. No data migration or state repair is required. During rollback propagation, agents may again over-block their own tunnel links.
+
+---
+
+## Conclusion
+
+The change is clear to ship. It addresses the observed Secret Drop and private-view false-positive without broadly weakening URL provenance.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** `not required by tooling`
+**Independent read of the artifact:** `not required`
+
+---
+
+## Evidence pointers
+
+- `tests/unit/convergence-check.test.ts`

package/upgrades/side-effects/project-map-related-worktrees.md

@@ -0,0 +1,85 @@
+# Side-Effects Review — Project Map Related Worktrees
+
+**Version / slug:** `project-map-related-worktrees`
+**Date:** `2026-05-29`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required by tooling`
+
+## Summary of the change
+
+This change extends Project Map with a concise related-worktrees summary and makes the headline total file count skip hidden directories consistently with the visible top-level breakdown. The existing project-root map remains the primary output, and related git worktrees are discovered only from configured roots plus the conventional agent worktree directory derived from the project directory name.
+
+## Decision-point inventory
+
+- `ProjectMapper.generate()` — add optional related-worktree metadata to generated maps.
+- `ProjectMapper.toMarkdown()` and `getCompactSummary()` — display related worktrees when present.
+- `ProjectMapper.countFiles()` — skip hidden directories consistently at every depth so hidden state does not inflate the headline total.
+
+---
+
+## 1. Over-block
+
+No blocking behavior changes. This is read-only reporting.
+
+---
+
+## 2. Under-block
+
+No authorization or safety gate changes. The mapper does not make worktree placement decisions and does not suppress existing worktree detector findings.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Project Map already owns spatial awareness for the current workspace. Reporting nearby conventional worktrees belongs at this layer because it helps the agent understand the real working surface without coupling the session-start context to worktree-manager internals.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no conversational block/allow surface.
+
+The output is informational. It helps orientation but does not authorize edits or replace coherence checks.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** None. Worktree safety remains owned by the worktree manager and detector.
+- **Double-fire:** None. Refresh still writes one JSON map and one markdown map.
+- **Races:** A worktree can be created or removed while the map is generating. The mapper handles missing or unreadable entries by skipping them, preserving refresh reliability.
+- **Feedback loops:** Positive loop: agents should be less likely to overlook the source worktrees they are actively using.
+
+---
+
+## 6. External surfaces
+
+Users and agents will see a related-worktrees section in Project Map JSON, markdown, and compact output when conventional worktrees exist. Agents without such worktrees keep effectively the same map, except headline totals become less noisy if hidden state directories were previously included.
+
+---
+
+## 7. Rollback cost
+
+Rollback is a normal code revert. Saved maps with the optional related-worktrees field remain harmless if older code ignores it.
+
+---
+
+## Conclusion
+
+The change is clear to ship. It fixes real spatial-awareness and count-consistency gaps found during Project Map dogfooding without widening the mapper into a broad filesystem scanner.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** `not required by tooling`
+**Independent read of the artifact:** `not required`
+
+---
+
+## Evidence pointers
+
+- `tests/unit/ProjectMapper.test.ts`
+- `tests/integration/coherence-routes.test.ts`