copilot-tap-extension 2.0.7 → 2.0.9

package/dist/skills/tap-goal/SKILL.md

@@ -133,13 +133,19 @@ Continuation rules:
 - If only 1 iteration remains and the goal is not complete, do not start broad new work. Produce a budget-limited handoff instead.
 - Do not treat budget exhaustion or a lifecycle "reached run budget" message as success.
 - If this iteration makes no progress-producing tool calls beyond required status/ledger bookkeeping and does not change evidence, call `tap_post` with `channel='<goal-emitter-name>'` and a no-action handoff, then stop the emitter rather than spinning.
+- If the remaining delta is unchanged from the previous ITERATION RECORD, post a STALLED LOOP record and stop rather than spending the rest of the budget.
 
 Evidence-audit rules:
 - Before marking complete, identify the verification surface from the goal contract.
 - Check the evidence directly: test output, benchmark result, file content, diff, generated artifact, source material, or other concrete proof.
+- When the evidence is a workspace file, EventStream entry, or already-run command result, call `tap_verify_goal_output` or `tap_audit_claims` before GOAL COMPLETE.
 - Check listed constraints for regressions.
 - If the verification surface cannot be checked, treat the goal as blocked, not complete.
 - Completion requires an explicit evidence audit in the final response and in the EventStream.
+- Wrap machine-readable EventStream records with explicit markers:
+  `=== BEGIN_ITERATION_RECORD ===` / `=== END_ITERATION_RECORD ===`,
+  `=== BEGIN_GOAL_COMPLETE ===` / `=== END_GOAL_COMPLETE ===`,
+  `=== BEGIN_GOAL_BLOCKED ===` / `=== END_GOAL_BLOCKED ===`.
 
 Research/audit goal rules:
 - For research, reproduction, audit, or investigation goals, maintain a claim ledger.
@@ -148,21 +154,26 @@ Research/audit goal rules:
 
 On this iteration:
 1. Briefly assess current progress toward the goal and the remaining iteration budget.
-2. If the goal is already achieved, first call `tap_post` with `channel='<goal-emitter-name>'` and a GOAL COMPLETE evidence audit in `message`, then call tap_stop_emitter for '<goal-emitter-name>' with scope='temporary', report that the goal is complete, and stop.
+2. If the goal is already achieved, first call `tap_verify_goal_output` or `tap_audit_claims` against the verification surface. If verification passes, call `tap_post` with `channel='<goal-emitter-name>'` and a marked GOAL COMPLETE evidence audit in `message`, then call tap_stop_emitter for '<goal-emitter-name>' with scope='temporary', report that the goal is complete, and stop.
 3. If the goal is blocked by missing information, permissions, failing external systems, or an unsafe action, first call `tap_post` with `channel='<goal-emitter-name>'` and a GOAL BLOCKED report in `message`, then call tap_stop_emitter for '<goal-emitter-name>' with scope='temporary', report the blocker, and stop.
-4. If this is the final iteration and the goal is not complete, do not start substantive new work. Call `tap_post` with `channel='<goal-emitter-name>'` and a BUDGET LIMITED summary in `message`: progress, evidence gathered, remaining work, and recommended next goal or budget. Then leave a concise handoff.
+4. If this is the final iteration and the goal is not complete, do not start substantive new work. Call `tap_post` with `channel='<goal-emitter-name>'` and a BUDGET LIMITED summary in `message`: progress, evidence gathered, remaining work, recommended next `/tap-goal ...` invocation, and suggested fresh budget. Then leave a concise handoff.
 5. Otherwise, choose the next smallest useful action toward the goal that fits the remaining budget and perform it.
 6. Validate the action using the repository's existing checks when relevant.
 7. End by calling `tap_post` with `channel='<goal-emitter-name>'` and an ITERATION RECORD in `message` containing:
    - iteration and budget used
    - action taken
    - evidence checked and result
+   - claim ledger entries when this is a research/audit goal
+   - remaining_delta or unchanged_delta status
    - current status: progressing, complete, blocked, or budget-limited
    - next best action
+   - branch, commit SHA, PR URL, run URL, or issue key when relevant
 8. End the user-visible response with the same concise progress update, what remains, and the next best step if the loop stops before completion.
 
 Safety rules:
 - Do not make unrelated changes.
+- Do not modify this goal emitter's own `every`, `everySchedule`, `maxRuns`, event filter, or goal contract while it is running unless the user explicitly asks.
+- Do not spawn additional emitters from this goal unless orchestration is explicitly part of the goal contract.
 - Do not mark the goal complete unless the objective is actually achieved and no required work remains.
 - Do not treat reaching the iteration budget as success.
 - Do not continue if the next step requires explicit user approval.

package/dist/skills/tap-loop/SKILL.md

@@ -7,6 +7,12 @@ user-invocable: true
 
 Create a timed or idle PromptEmitter with `tap_start_emitter`.
 
+If the request includes a completion condition such as "until", "keep going
+until", "stop when", "work until done", or "iterate until complete", do not
+create a plain loop. Redirect to `/tap-goal` semantics instead, because the
+user is asking for a completion contract with evidence, budget, and stop
+conditions rather than a recurring prompt.
+
 ## Expected input
 
 Interpret the invocation as:

package/dist/skills/tap-monitor/SKILL.md

@@ -63,9 +63,25 @@ Steps:
    - Lines that indicate important events (errors, warnings, state changes) → candidates for `{ "match": "...", "outcome": "inject" }`.
    - Lines that are never relevant at all → candidates for tighter keep/drop rules.
 4. Compare what you see against the current filter patterns for emitter '<command-emitter-name>'.
-5. Only update if the evidence clearly justifies a change (signal-to-noise is poor or a pattern is clearly wrong).
-6. If an update is needed, call tap_set_event_filter with the revised patterns for emitter '<command-emitter-name>'.
-7. Do not report your findings to the user unless you made a change. If you made a change, send one short message describing what you updated and why.
+5. Use this shared contract when judging the stream:
+   - stream_purpose: <why the user wanted this monitor>
+   - signal_vocabulary: errors, warnings, failures, state changes, explicit success/failure markers
+   - noise_vocabulary: timestamps-only, heartbeat-only, repeated unchanged status, empty pings
+6. Only update if the evidence clearly justifies a change (signal-to-noise is poor or a pattern is clearly wrong).
+7. If an update is needed, call tap_set_event_filter with the revised patterns for emitter '<command-emitter-name>'.
+8. Always call tap_post with channel '<stream-name>' and a REVIEW RECORD wrapped in markers:
+   === BEGIN_REVIEW_RECORD ===
+   {
+     "reviewed_at": "<ISO timestamp>",
+     "entries_examined": <number>,
+     "issue_type": "noise_pattern|missed_signal|over_filtering|duplicate_inject|no_change",
+     "patterns_changed": ["short label for each change"],
+     "remaining_noise_delta": ["what still looks noisy or uncertain"],
+     "signal_vocabulary": ["terms treated as signal"],
+     "noise_vocabulary": ["terms treated as noise"]
+   }
+   === END_REVIEW_RECORD ===
+9. Do not report your findings to the user unless you made a change. If you made a change, send one short message describing what you updated and why.
 ```
 
 Substitute the real emitter name and stream name into the prompt before passing it to `tap_start_emitter`.

package/dist/skills/tap-orchestrate/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: tap-orchestrate
+description: "Create a coordinator PromptEmitter for multi-agent tap workflows with role-specific sub-emitters, gated handoffs, and evidence records. Use when the user asks to orchestrate multiple agents, roles, workstreams, or parallel implementation/review/test phases."
+argument-hint: "<objective and roles>"
+user-invocable: true
+---
+
+Create a coordinator PromptEmitter that manages a multi-agent workflow using tap
+emitters and EventStreams.
+
+Use this for work that naturally decomposes into roles such as planner,
+implementer, reviewer, tester, documenter, provider-builder, or release
+coordinator. Do not use it for a single straightforward task.
+
+## What to create
+
+Use `tap_start_emitter` to create a **coordinator PromptEmitter**:
+
+- Name: `orchestrate-<objective-slug>`.
+- Prompt: a self-contained orchestration contract.
+- Schedule: `everySchedule = ["2m", "5m", "10m"]`.
+- `lifespan = "temporary"` unless the user explicitly asks for persistence.
+- `ownership = "modelOwned"`.
+- `subscribe = false`.
+- `maxRuns = 50` unless the user gives a budget.
+
+The coordinator may create role-specific PromptEmitters only when the role has a
+clear deliverable and verification surface. Each role emitter should write its
+handoff to an EventStream with a stable name:
+
+```text
+orchestrate-<objective>-<role>
+```
+
+## Coordinator prompt contract
+
+The coordinator prompt must include:
+
+```text
+Objective: <user objective>
+Roles: <role list, deliverables, and verification surface>
+Gate policy:
+- Do not hand off to the next role until required artifacts or EventStream notes exist.
+- Read role EventStreams with tap_stream_history before deciding a gate is satisfied.
+- If parallel work is safe, create independent role emitters in the same iteration.
+- If a role blocks, post ORCHESTRATION BLOCKED and stop the coordinator.
+Audit trail:
+- After every decision, call tap_post to the coordinator stream with ORCHESTRATION RECORD:
+  role, gate, evidence checked, decision, next handoff.
+Safety:
+- Do not spawn duplicate role emitters.
+- Do not mutate another role's scope unless the coordinator evidence supports it.
+- Stop all role emitters when the orchestration completes or blocks.
+```
+
+## Required behavior
+
+1. Parse the objective and any requested roles.
+2. If roles are missing, infer a minimal role set from the objective:
+   planner, implementer, reviewer, validator.
+3. Create the coordinator PromptEmitter only; do not immediately create role
+   emitters in the setup turn. The coordinator will create them when it runs.
+4. Confirm:
+   - coordinator emitter name and stream
+   - roles
+   - gate policy
+   - max iteration budget
+
+## Good role patterns
+
+- **planner**: produce plan and boundaries; verification is a plan note.
+- **implementer**: make code/doc changes; verification is diff + focused checks.
+- **reviewer**: inspect changes; verification is review note with findings.
+- **validator**: run tests/build/evals; verification is command evidence.
+- **release**: bump/push/publish only after validator passes.
+
+## When not to use
+
+Do not create orchestration for a normal `/tap-goal` objective that one agent can
+complete directly. Orchestration adds coordination cost and should only be used
+when parallel roles or gated handoffs are genuinely useful.

package/dist/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "2.0.7"
+  "version": "2.0.9"
 }

package/docs/adr/0001-persistent-config-default-ownership.md

@@ -0,0 +1,33 @@
+# ADR 0001: Persistent config emitters default to user ownership
+
+## Status
+
+Accepted
+
+## Context
+
+No `docs/adr/0000-template.md` existed when this ADR was written, so this file uses the standard ADR sections.
+
+The project documentation treats on-disk emitter definitions as persistent workflows and recommends `userOwned` ownership for persistent, recurring, or policy-bearing emitters. Existing normalization code defaulted missing persisted emitter ownership and lifespan to `modelOwned` and `temporary`, even though configured emitters are restored from disk and listed as persistent definitions.
+
+That mismatch can weaken the protection model for manually edited config files: an emitter with no explicit ownership may be treated as model-owned during normalization even though it came from persistent user config.
+
+## Decision
+
+Persisted/on-disk emitter definitions default to:
+
+- `ownership: "userOwned"`
+- `lifespan: "persistent"`
+
+Normalization still honors explicit compatibility fields:
+
+- `ownership` or legacy `managedBy`, including explicit `modelOwned`
+- `lifespan` or legacy `scope`, including explicit `temporary`
+
+Runtime-created temporary/model-owned emitters keep their explicit normalized fields when serialized, so this default only applies when persisted config omits ownership/lifespan signals.
+
+## Consequences
+
+- Manually authored config aligns with the documented safety default for persistent workflows.
+- Legacy config with explicit `modelOwned` or `temporary` remains compatible.
+- Future changes that alter config ownership/lifespan defaults should update or supersede this ADR.

package/docs/adr/0002-local-provider-gateway-runtime-security.md

@@ -0,0 +1,36 @@
+# ADR 0002: Local provider gateway token and runtime shutdown boundary
+
+## Status
+
+Accepted
+
+## Context
+
+No `docs/adr/0000-template.md` exists, so this ADR follows the existing ADR style.
+
+The provider gateway lets local external processes register tools with a Copilot session over WebSocket. That boundary needs safe defaults for network exposure, token discovery, token lifetime, and shutdown cleanup. ADR 0001 covers persisted emitter ownership defaults and does not cover provider gateway security or runtime lifecycle. The extension entrypoint should not own provider protocol details; it delegates session lifecycle handling to the runtime facade.
+
+Providers may be launched from the active Copilot environment, from a sibling terminal, or via the provider SDK. Sibling processes cannot reliably inherit `TAP_PROVIDER_TOKEN`, so the gateway needs a local discovery path without turning the token into durable configuration.
+
+## Decision
+
+- The provider WebSocket gateway binds to loopback by default: `127.0.0.1:9400`. Any non-loopback host must be an explicit runtime override.
+- On gateway start, generate a fresh provider token for the running gateway instance.
+- Publish the token in both supported discovery locations:
+  - `TAP_PROVIDER_TOKEN` in the gateway process environment.
+  - `<COPILOT_HOME or ~/.copilot>/extensions/tap/.provider-token` for sibling local providers and SDK auto-discovery.
+- Create the token directory with restrictive permissions (`0700`) and write the token file with restrictive permissions (`0600`), including a best-effort chmod after write.
+- Treat the token file as runtime state, not config: remove it and clear `TAP_PROVIDER_TOKEN` when the gateway stops.
+- On session shutdown, the runtime facade owns provider lifecycle coordination. Entrypoints delegate shutdown listener registration to the cached runtime, which de-duplicates the effective `session.shutdown` handler across extension reloads and logs cleanup failures instead of allowing fire-and-forget rejections. The runtime sends `session.lifecycle` with `state: "shutdown.pending"` and a runtime-owned deadline (currently 10 seconds). Stop accepting new gateway connections immediately, but keep existing provider sockets open until they send `goodbye`, all sockets drain, or the deadline expires. After the deadline, close remaining provider sockets.
+- Runtime session-shutdown cleanup uses the shutdown-specific emitter wait path from ADR 0003 before reporting cleanup complete; ordinary user/tool stop requests remain non-blocking stop requests.
+- Bound-provider protocol failures that can represent an in-flight tool call's terminal response must fail deterministically. If a malformed message, oversized message, invalid `tool.result`, or syntactically valid `tool.result` with an unknown call id cannot be correlated while provider calls are pending, reject exactly one pending call with the protocol/validation error. If multiple calls are pending and correlation is impossible, disconnect the provider and reject all pending calls with `DISCONNECTED`. Unknown-id `tool.result` messages are protocol errors and are not delivered to normal tool-result callbacks.
+
+## Consequences
+
+- Local providers can connect from sibling terminals without manually copying environment variables, while the gateway remains limited to loopback by default.
+- Token exposure is scoped to the current OS user profile and gateway runtime. The token is still bearer auth, so users must not share it or expose the token file to untrusted processes.
+- Gateway stop acts as token revocation by deleting the token file and clearing the environment value.
+- Providers get a bounded cleanup window during session shutdown, avoiding abrupt termination when they respond promptly and preventing indefinite shutdown hangs when they do not.
+- Repeated extension reloads do not accumulate active shutdown cleanup handlers against the cached runtime, and rejected async shutdown cleanup is visible in stderr/session diagnostics.
+- Invalid or uncorrelatable terminal provider behavior cannot leave Copilot-facing tool promises pending indefinitely, including tools without declared timeouts. Some parse/payload errors remain non-fatal when no calls are pending, but become fail-fast while ambiguous in-flight calls could otherwise be orphaned.
+- Future changes to provider token discovery, host binding, token persistence, runtime shutdown ownership/deadlines/listener ownership, or pending-call fail-fast semantics should update or supersede this ADR.

package/docs/adr/0003-emitter-delivery-lifecycle.md

@@ -0,0 +1,68 @@
+# ADR 0003: Emitter delivery lifecycle is retryable and transactional
+
+## Status
+
+Accepted
+
+## Context
+
+No `docs/adr/0000-template.md` exists, so this ADR follows the existing ADR style.
+
+Persistent emitter auto-start, stream session-injector policy, notification delivery, and supervisor persistence happen across separate modules. A persistent emitter may produce output during session startup, before the Copilot session is attached to the cached runtime, and it may route `surface` or `inject` outcomes through the stream's session injector immediately.
+
+The lifecycle contract needs to avoid these failure modes:
+
+- auto-started persistent emitters must not silently suppress `surface`/`inject` outcomes when no explicit stream injector is configured;
+- queued notification delivery must not discard a batch solely because the session is not attached yet;
+- a failed persistent start must not report failure while leaving a newly-started emitter running outside durable config.
+- startup surface logs must not disappear when emitters produce `surface` output before the Copilot session object is attached to the cached runtime.
+- session shutdown cleanup must not report completion before child processes close, except through a bounded timeout path.
+- idle PromptEmitters auto-started during session startup must not remain `WAITING` forever solely because the initial `session.idle` transition happened before the runtime's session activity bridge was attached.
+
+## Decision
+
+- Config bootstrap preserves explicit `subscribe: false` on emitter definitions.
+- When a persistent stream already has a configured session injector, auto-start does not overwrite that injector during emitter start; the persisted stream policy remains authoritative.
+- When no explicit stream injector is configured for the emitter stream, bootstrap allows the emitter's normal subscription default to apply so `surface`/`inject` filter outcomes have an enabled delivery path.
+- Notification dispatch removes a batch from the queue only for an attempted send, and requeues that batch at the front when delivery fails because the session is not attached. Retry is delayed and single-flight to avoid tight retry loops while preserving notification ordering. The retry queue is bounded in memory: new updates are dropped when the queue is full, and retry requeues preserve the failed batch at the front while dropping any overflow from the tail. Drops are reported through session diagnostics.
+- Session end/shutdown advances the notification dispatch generation, cancels pending retry timers, and clears queued-but-unsent notifications so stale background updates from one Copilot session cannot be injected into a later session.
+- Session timeline logs emitted before initial attach are queued in bounded memory by the session port and replayed after attach. This covers startup `surface` delivery races without changing post-attach logging behavior.
+- Supervisor start is transactional around newly-started emitters: if post-start persistence fails, the supervisor requests a bounded stop-and-wait for the new emitter, removes/restores the in-memory emitter entry after the stop settles, restores the prior session-injector state, and best-effort restores the previous persistent emitter config before surfacing the failure. If the bounded rollback wait times out or stop fails, the runtime emitter entry and current injector state remain visible for manual cleanup while durable config is still restored best-effort.
+- Bootstrap restoration of an emitter that already exists in persistent config is
+  a runtime-only start path. When bootstrap does not request any durable
+  mutation, supervisor start skips config rewrites and persistence rollback so a
+  read-only or temporarily unwritable config file cannot by itself prevent
+  auto-start recovery. User-initiated persistent starts and persistent injector
+  updates continue to use the transactional persistence behavior above.
+- Scheduled emitter iterations must clear `inFlight` in a `finally` path and convert unexpected thrown/rejected iteration failures into deterministic failed iteration results so unhandled rejections cannot strand an emitter in `RUNNING`.
+- Ordinary emitter `stop()` remains a request/transition operation for tool compatibility. Shutdown uses a separate wait path that requests stop, waits for child `close`/in-flight completion, and returns per-emitter outcomes (`stopped`, `timedOut`, or `failed`) instead of discarding timeout/rejection details. Hook cleanup summaries report those outcomes rather than claiming unconditional success.
+- After session listeners are attached, the runtime synthesizes one initial idle lifecycle nudge by marking the session port idle and calling the supervisor's existing `onSessionIdle()` path. Later real activity events clear scheduled idle work through the normal session-activity transition. This gives persistent idle PromptEmitters auto-started during `onSessionStart` a deterministic first scheduling path even when the SDK does not replay an already-observed `session.idle` event to late listeners.
+- CommandEmitter event delivery is resolved through the shared stream delivery policy seam, preserving the existing EventFilter + SessionInjector matrix:
+  - `drop` stores nothing and increments the dropped-line count.
+  - `keep` stores the event and surfaces it only when the stream SessionInjector is enabled with `delivery: "all"`.
+  - `surface` stores the event and surfaces it only when the stream SessionInjector is enabled with `delivery: "surface"` or `delivery: "all"`.
+  - `inject` stores the event and enqueues session injection when the stream SessionInjector is enabled with `delivery: "important"`, `"all"`, `"surface"`, or `"inject"`; it surfaces only for enabled `delivery: "surface"` or `"all"`.
+  - Nullish SessionInjector delivery continues to default to `surface`; disabled SessionInjectors and `keep`/`drop`/unknown non-null delivery modes do not proactively surface or inject.
+- System notifications emitted by the line router continue to use the same SessionInjector injection decision for enqueueing, but they are not timeline-surfaced by that path.
+- `handlePromptResult()` remains append-only compatibility code; this decision does not introduce PromptEmitter assistant-response capture.
+
+## Consequences
+
+- Persistent emitters with `inject` or `surface` event-filter outcomes can deliver immediately after auto-start without requiring a duplicate stream entry.
+- User-configured persistent stream injector policy remains the source of truth when both a stream definition and an emitter definition exist.
+- Session startup races defer notification delivery instead of losing background events.
+- Startup surface events can appear after attach instead of being silently suppressed by a temporarily detached session port.
+- Startup idle PromptEmitters can run after attach without waiting for a second idle transition; if real session activity follows attach, the existing activity bridge cancels the pending idle timer.
+- Retried notifications retain FIFO order relative to later queued updates that remain inside the bounded retry queue; deterministic overflow drops prefer preserving older/retried work over newer tail entries.
+- Session lifecycle clearing prevents queued notification retries from crossing session boundaries.
+- A caller that sees persistent emitter start fail should not also have a hidden running emitter to clean up; if rollback cannot confirm settlement before the bounded timeout, the emitter remains visible in runtime state for manual cleanup.
+- Persistent emitter auto-start from config can succeed even when the existing
+  config file cannot be rewritten, provided no durable state change was
+  requested by bootstrap.
+- Shutdown cleanup can wait for real process closure without changing the public meaning of user/tool stop requests, and session summaries can distinguish emitters that stopped, timed out, or failed during cleanup.
+- The shared delivery seam centralizes CommandEmitter delivery decisions without changing EventFilter outcomes, SessionInjector authority, notification retry behavior, or PromptEmitter capture semantics.
+- Future changes to auto-start subscription defaults, bootstrap persistence
+  writes, notification/log replay policy, attach-time idle nudging, scheduled
+  iteration failure handling, notification retry bounds/session clearing,
+  shutdown wait reporting behavior, or supervisor start rollback semantics
+  should update or supersede this ADR.

package/docs/adr/0004-persistent-config-canonical-streams.md

@@ -0,0 +1,86 @@
+# ADR 0004: Persistent config stream injector and alias semantics
+
+## Status
+
+Accepted
+
+## Context
+
+No `docs/adr/0000-template.md` exists, so this ADR follows the existing ADR style.
+
+ADR 0001 records that persisted emitter definitions default to user-owned,
+persistent ownership semantics. Persistent stream definitions have the same
+on-disk/user-authored character, but session-injector normalization defaulted
+missing ownership and lifespan to model-owned, temporary values while runtime
+bootstrap applied persisted streams as user-owned, persistent definitions.
+
+Emitter config also has two names for the destination EventStream:
+
+- `stream` is the documented config field.
+- `channel` is a legacy alias still accepted by older tools and config files.
+
+Keeping both fields in normalized/serialized config lets a stale `channel`
+silently override an edited `stream` in runtime paths that consume only
+`channel`.
+
+## Decision
+
+- Persisted stream `sessionInjector` entries default to:
+  - `ownership: "userOwned"`
+  - `lifespan: "persistent"`
+- Explicit compatibility fields are still honored:
+  - `ownership` or legacy `managedBy`
+  - `lifespan` or legacy `scope`
+- `stream` is the canonical persisted emitter destination field.
+- `channel` remains accepted as an input alias for backwards compatibility.
+- When both `stream` and `channel` are present and conflict, `stream` wins.
+- Normalization and serialization drop the legacy `channel` alias after resolving
+  the canonical `stream`, preventing stale aliases from being persisted again.
+- Runtime emitter normalization and configured-emitter projection prefer
+  `stream` over `channel` so user-authored config and runtime routing agree.
+- Config migration persistence is best-effort: loading a readable config should
+  succeed even if saving the canonical migrated form fails. The store should skip
+  the migration save when the parsed on-disk JSON is already canonically equal.
+- Config loading is transactional. The store builds candidate cwd/path/config
+  state in locals and commits it only after read, parse, and migration all
+  succeed, or after the config search completes successfully with no file found.
+  If a load fails, the previous runtime config remains active and subsequent
+  saves are refused until a later load succeeds.
+- Persisted stream entries must include an explicit, non-blank string `name`.
+  `name: "main"` remains valid, but missing, blank, non-string, or otherwise
+  non-normalizable names are config validation errors and are never defaulted to
+  `main`.
+- A persisted stream entry with only metadata such as `name` and `description`
+  does not define durable SessionInjector policy. Applying such an entry keeps
+  the runtime injector on the non-protected default
+  (`modelOwned`/`temporary`, disabled) instead of synthesizing a
+  `userOwned`/`persistent` injector. Only an explicit `sessionInjector` or
+  legacy `subscription` object receives the persisted stream injector defaults
+  above.
+- Bootstrap auto-start of emitter definitions already present in config is a
+  runtime restoration path, not a durable config update. It must not require a
+  config rewrite when no persisted emitter or stream policy is being changed.
+
+## Consequences
+
+- Hand-authored stream injector config aligns with runtime persistent semantics
+  and the user-owned defaults documented for durable workflows.
+- Existing channel-only config remains valid and is migrated to `stream`.
+- Editing `stream` is deterministic even if an old `channel` field remains.
+- Read-only or temporarily unwritable config files no longer prevent the
+  extension from using an otherwise valid config; users receive a warning when
+  canonical migration persistence fails.
+- Malformed or unreadable config files cannot replace the last known-good
+  runtime config and cannot be overwritten later by an empty or partially loaded
+  state via `save()`.
+- Malformed persisted stream entries fail config normalization instead of
+  silently enabling or modifying the default `main` stream.
+- Bare persisted stream entries preserve stream metadata without turning normal
+  unforced SessionInjector updates into protected user-owned mutations.
+- Auto-start restoration can recover already-persisted emitters from a
+  read-only config file, while user-initiated durable emitter starts and stream
+  injector changes still persist and roll back on save failure.
+- Future changes to persistent config defaults, stream-name validation, emitter
+  destination aliases, transactional load/save safety, bootstrap restoration
+  writes, or migration write-failure behavior should update or supersede this
+  ADR.

package/docs/adr/0005-provider-sdk-push-and-dynamic-tools.md

@@ -0,0 +1,48 @@
+# ADR 0005: Bound-provider SDK push and dynamic tools
+
+## Status
+
+Accepted
+
+## Context
+
+No `docs/adr/0000-template.md` exists, so this ADR follows the existing ADR style.
+
+The provider SDK exposes `push`, `surface`, `keep`, and `updateTools`. Detour already calls `provider.push()`. Before this decision, the gateway accepted only `auth`, `hello`, `tool.result`, and `goodbye` from providers after binding, so SDK pushes and dynamic tool updates were rejected as unknown message types.
+
+The full provider-interface design contains broader advanced-provider features such as hooks updates, context updates, stream queries, subscriptions, all-session binding, pairing auth, revisions, and update acknowledgments. Those features are intentionally outside this follow-up.
+
+## Decision
+
+- A provider must still authenticate and send `hello` for exactly one active session before using the new messages.
+- While Bound, a provider may send `push` with:
+  - `level`: `keep`, `surface`, or `inject`
+  - `event`: non-empty text
+  - optional `stream`, defaulting in the SDK to the provider name
+  - optional `sessionId`, which must match the session selected in `hello`
+  - optional object `metadata`
+- Explicit push stream names use the same canonical EventStream identifier rules as stream tools. The gateway rejects non-normalizable stream names instead of falling back to `main`; accepted pushes use the canonical stream name consistently for storage, notifications, and return values. If a push omits `stream`, the runtime uses the canonical provider name/id when possible and otherwise falls back to `main`.
+- Push delivery is immediate and session-bound:
+  - `keep` appends to the EventStream only.
+  - `surface` appends and logs to the Copilot timeline.
+  - `inject` appends, logs, and enqueues a session injection through the existing retrying notification dispatcher.
+- Provider push delivery uses the shared stream delivery policy seam in provider-authoritative mode. The provider-selected `level` remains the complete delivery policy for that push: provider `inject` is not gated by the destination stream's SessionInjector, and provider `keep`/`surface` semantics are unchanged.
+- Provider push surfacing is best-effort: timeline logging failures must not create unhandled promise rejections or prevent the already-appended stream event from remaining stored.
+- While Bound, a provider may send `tools.update` with a complete replacement `tools` array using the same validation and 100-tool cap as `hello.tools`.
+- `tools.update` is accepted only for the bound session. A supplied `sessionId` must match the session selected in `hello`.
+- Successful `tools.update` replaces the provider's registry entry, updates the connection's active tool definitions, and schedules the same debounced session tool refresh used by provider connect/disconnect.
+- Rejected `tools.update` messages leave the previous provider tool list active.
+- Existing in-flight tool calls are not cancelled when a successful update removes their tool definition; they continue to their result, timeout, cancellation, or disconnect outcome.
+- `hello.ack` may include `sessionId` so SDK providers can observe the bound session.
+- This minimal contract does not add hooks updates, context updates, stream queries, subscriptions, all-session binding, pairing auth, per-update revisions, or success acknowledgments.
+
+## Consequences
+
+- SDK providers can use `provider.push()`, `provider.surface()`, `provider.keep()`, and `provider.updateTools()` without being rejected by the gateway.
+- Detour page messages can reach the Copilot session instead of failing as unknown provider messages.
+- The shared delivery seam records the provider delivery matrix alongside CommandEmitter delivery policy while preserving this ADR's existing `keep`/`surface`/`inject` behavior.
+- Invalid provider-selected stream names fail closed instead of silently misrouting events into `main`.
+- Dynamic tools remain simple and deterministic: each update replaces the provider's complete tool list and reuses the existing reload path.
+- Providers do not receive a success ack for `tools.update`; they should treat absence of `error` as success in the minimal profile.
+- The gateway remains single-session-bound for external providers, preserving the current security boundary.
+- Future changes to provider push semantics, dynamic tool update acknowledgments/revisions, multi-session binding, pairing auth, or advanced provider capabilities should update or supersede this ADR.

package/docs/adr/0006-command-emitter-cwd-workspace-boundary.md

@@ -0,0 +1,46 @@
+# ADR 0006: Command-emitter cwd stays within the session workspace
+
+## Status
+
+Accepted
+
+## Context
+
+No `docs/adr/0000-template.md` exists, so this ADR follows the existing ADR style.
+
+Command emitters accept an optional `cwd` field so a watcher can run from a
+subdirectory such as `services/api`. Before this decision, `cwd` resolution used
+`path.resolve(sessionCwd, requestedCwd)`, which also accepted absolute paths and
+relative traversal that escaped the Copilot session working directory.
+
+That behavior made a model-supplied emitter request capable of changing the
+process working directory outside the workspace boundary selected for the
+session. ADR 0001 and ADR 0004 cover persistent ownership/config defaults, and
+ADR 0002 covers provider gateway security; they do not define command-emitter
+working-directory boundaries.
+
+## Decision
+
+- Command-emitter `cwd` is interpreted as a path relative to the session cwd.
+- Omitted or blank `cwd` uses the session cwd.
+- `cwd: "."` is allowed and resolves to the session cwd.
+- Subdirectories under the session cwd are allowed.
+- Absolute `cwd` values are rejected.
+- Relative paths that resolve outside the session cwd, including `..` traversal,
+  are rejected.
+- This is API hardening for emitter configuration. It is not a shell sandbox:
+  the spawned command still runs with the user's normal OS permissions, and the
+  command itself may access files or change directories according to those
+  permissions.
+
+## Consequences
+
+- Tool callers and persisted configs must express command-emitter working
+  directories as workspace-relative paths.
+- Existing configs that used absolute paths or traversal outside the session cwd
+  will fail validation during auto-start until rewritten as in-workspace
+  relative paths.
+- The session cwd remains the durable boundary for command-emitter placement,
+  reducing accidental or model-initiated execution from unrelated directories.
+- Future changes to command-emitter cwd resolution, workspace-boundary behavior,
+  or stronger process sandboxing should update or supersede this ADR.

package/docs/adr/0007-runtime-session-workspace-context.md

@@ -0,0 +1,62 @@
+# ADR 0007: Runtime session workspace context boundary
+
+## Status
+
+Accepted
+
+## Context
+
+No `docs/adr/0000-template.md` exists, so this ADR follows the existing ADR
+style.
+
+Runtime services previously shared the active session workspace through loose
+getter/setter cwd closures. That made the mutable cwd boundary easy to
+thread through services but left ownership split across runtime subsystem
+bootstrap, config loading, emitter service fallback behavior, and supervisor cwd
+validation.
+
+ADR 0004 requires persistent config loading to be transactional: failed loads
+must not replace the last-known-good config state. ADR 0006 requires
+command-emitter `cwd` values to remain relative to the session workspace and to
+be validated by the existing workspace-boundary rules. Those decisions remain
+the source of truth for config safety and emitter cwd semantics; this ADR records
+where the runtime owns the shared session/workspace context.
+
+## Decision
+
+- Introduce a runtime-owned session/workspace context for active session
+  identity metadata, current session/base cwd, current config cwd, and emitter
+  cwd resolution.
+- Runtime subsystem construction creates or receives this context once and then
+  hands out narrow capability views:
+  - config bootstrap receives config cwd resolution/commit capabilities;
+  - emitter services and supervisor receive emitter cwd resolution capabilities.
+- Config bootstrap resolves the candidate cwd before loading config, then
+  commits the runtime context's base/config cwd only after `configStore.load()`
+  succeeds or completes the no-config-found path. This keeps runtime cwd
+  ownership aligned with ADR 0004 last-known-good load semantics.
+- Emitter cwd resolution remains delegated to the existing path validation
+  helpers, preserving ADR 0006 behavior:
+  - omitted, blank, or `.` emitter `cwd` uses the session cwd;
+  - subdirectories under the session cwd are allowed;
+  - absolute paths and traversal outside the session cwd are rejected;
+  - this remains cwd placement hardening, not a shell sandbox.
+- Emitter start fallback preserves the prior nullish-only base cwd behavior:
+  omitted/null base cwd options use the current session cwd, while explicitly
+  supplied base cwd values are normalized as supplied.
+- Public tool names, provider protocol behavior, emitter delivery semantics,
+  persistence defaults, and config canonicalization rules are unchanged.
+
+## Consequences
+
+- The mutable session/workspace boundary has one owner instead of ad hoc closure
+  plumbing across services.
+- Dependency injection remains capability-specific: consumers receive config or
+  emitter workspace capabilities rather than a broad runtime object.
+- Failed config loads cannot advance the runtime context's config/base cwd ahead
+  of the last-known-good config load state.
+- Command-emitter cwd validation remains centralized on the existing helper and
+  keeps the ADR 0006 workspace-relative contract.
+- Future changes to runtime session/workspace ownership, config cwd commit
+  timing, base cwd fallback semantics, or emitter cwd validation ownership
+  should update or supersede this ADR.

package/docs/evals.md

@@ -0,0 +1,41 @@
+# Evals
+
+Testing infrastructure for copilot-tap-extension.
+
+## Quick validation
+
+```bash
+npm run check              # syntax check
+npm run evals:smoke        # smoke test
+npm run evals:validate-modes  # interactive vs prompt-mode gap
+```
+
+## How the eval runner works
+
+`evals/run.mjs` starts one ACP server, creates fresh SDK sessions, and mounts the shared runtime from `src/tap-runtime.mjs` directly into those sessions. This means `smoke` and `run` exercise the same EventStream/EventEmitter logic as the extension without depending on `.github/extensions` being discovered in a headless session.
+
+The runner writes prompt, response, error, and full event-transcript artifacts under `evals/results/...`.
+
+## Supported paths
+
+The reliable supported paths are:
+
+1. **Interactive foreground Copilot sessions**
+2. **ACP/SDK sessions that mount the shared runtime directly**
+
+Do **not** treat headless prompt-mode or other non-interactive repo-extension loading as reliable. Use `validate-modes` to prove that distinction.
+
+## Extension-loader evals
+
+The real repo-scoped extension loader is validated separately. `npm run evals:validate-modes` probes `copilot -p` with the actual `.github/extensions` entrypoint, then compares with the same prompt in an interactive session.
+
+For interactive executor evals:
+
+```bash
+node evals/run.mjs prepare-interactive --case E001
+# run the printed prompt inside an interactive `copilot` session
+# then run the printed /share command
+node evals/run.mjs judge-interactive --run-dir "<printed-run-dir>"
+```
+
+This keeps the executor in a foreground Copilot session where the extension can attach, uses `/share <path>` to persist the transcript, and runs a tool-free ACP judge against the transcript plus config snapshots. If you reuse one session for multiple cases, run `/clear` before each next case.