<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-09-26-3-hosted-interaction-opt-in/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-09-26-3-hosted-interaction-opt-in/</id>
  <title>ADR: hosted interaction is opt-in, twice, with no packaged endpoint</title>
  <updated>2026-09-26T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-09-26-3-hosted-interaction-opt-in/"/>
  <summary>Reverses the #3980 packaged hosted-endpoint default and records the two-scope live-drain consent model plus the ledger-projection flag this mission ships (#4971).</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Team Kitty’s server side has been frozen for development while the SaaS and Zeitgeist relay
mature. Against that freeze, the CLI still shipped a hard-coded live default
(&lt;code dir=&quot;auto&quot;&gt;https://team.spec-kitty.ai&lt;/code&gt;, #3980) and automatically fanned status, lifecycle, runtime, and
decision moments out to it whenever an endpoint resolved — with no per-developer or per-repository
consent step. On 2026-09-23 the operator directed that the shipped build stop targeting a live
hosted server on its own: nothing should leave a fresh install’s machine unless the developer has
explicitly opted in.&lt;/p&gt;
&lt;p&gt;There is a gap in the record this ADR closes first. Mission &lt;code dir=&quot;auto&quot;&gt;team-kitty-launch-defaults-01M1XJ4Y&lt;/code&gt;
WP01 &lt;em&gt;planned&lt;/em&gt; the ADR that would have recorded the original packaged-default decision
(&lt;code dir=&quot;auto&quot;&gt;2026-09-07-1-packaged-hosted-target-default.md&lt;/code&gt;), but that file was &lt;strong&gt;never written&lt;/strong&gt;
(research.md R4 for this mission). Reversing an undocumented decision has no prior record to
amend, so this ADR is the sole governance record covering both the original packaged-default
decision this mission reverses and the new two-scope drain consent model that replaces it.&lt;/p&gt;
&lt;p&gt;Two further constraints shaped the design:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The committed lane ledger (&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;) and decision ledger (&lt;code dir=&quot;auto&quot;&gt;decisions/&lt;/code&gt;) are a
non-optional floor (“Git carries DONE”, #4311) — no opt-in flag in this mission may be able to
stop them being written or committed, only the &lt;em&gt;automatic outbound hosted&lt;/em&gt; side effects.&lt;/li&gt;
&lt;li&gt;A future bounded live-publish retry for #4311 is anticipated but not yet on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;; whatever gate
this mission adds must also bind that future edge, not just today’s callers (C-005).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Reverse the packaged default and replace it with a two-scope, explicit opt-in (“drain”) plus a
narrower, unrelated flag for the local execution-state projection (“ledger”). Recorded verbatim in
spirit from the mission’s Operator decisions table and its post-spec squad resolutions:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;D-1 — Drain lives in two places, both required.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;hosted.drain&lt;/code&gt;
(repository opt-in) &lt;strong&gt;and&lt;/strong&gt; the developer’s runtime-root &lt;code dir=&quot;auto&quot;&gt;config.toml&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;[hosted] drain&lt;/code&gt;
(personal activation). Effective drain requires both on; either off or absent is off. Managed by
&lt;code dir=&quot;auto&quot;&gt;spec-kitty moments drain on|off|status [--repo]&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D-2 / FR-010 — The ledger flag gates only the derived projection.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; →
&lt;code dir=&quot;auto&quot;&gt;ledger.projection&lt;/code&gt; (default &lt;code dir=&quot;auto&quot;&gt;true&lt;/code&gt;) gates automatic refresh of the gitignored, derived,
always-rebuildable local execution-state projection under &lt;code dir=&quot;auto&quot;&gt;.kittify/derived/&amp;#x3C;mission&gt;/&lt;/code&gt; — never
the lane ledger, its commit, the committed status snapshot, the decision ledger, the run journal,
or invocation records. The two flags are orthogonal axes: one gates outbound network side
effects, the other gates a purely local, re-derivable read model.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D-3 — Explicit vs automatic guidance split.&lt;/strong&gt; An explicit hosted command run with no configured
endpoint stops with setup guidance naming &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SAAS_URL&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;config.toml [sync].server_url&lt;/code&gt;, no traceback (&lt;code dir=&quot;auto&quot;&gt;HostedEndpointUnconfigured&lt;/code&gt;) — most such commands exit
non-zero, but a status-reporting command (&lt;code dir=&quot;auto&quot;&gt;auth status&lt;/code&gt;) exits 0 with the same guidance, since
reporting “not configured” is itself a successful answer. An automatic path (a lane transition, a
lifecycle beat) resolves the endpoint via &lt;code dir=&quot;auto&quot;&gt;resolve_server_target_or_none()&lt;/code&gt; and stays silent when
none is configured.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;FR-004 — Widen and interview startup skip their hosted prereq probe when drain is off.&lt;/strong&gt; (Not
independently lettered in the Operator decisions table; folded into FR-004’s “every automatic
hosted egress” requirement, not to be confused with plan.md’s unrelated “D7” personal-writer
strictness label.) &lt;code dir=&quot;auto&quot;&gt;widen/prereq.py::check_prereqs&lt;/code&gt; and the charter/specify/plan interview
startups
(&lt;code dir=&quot;auto&quot;&gt;cli/commands/charter/interview.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;missions/plan/plan_interview.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;missions/plan/specify_interview.py&lt;/code&gt;) each check &lt;code dir=&quot;auto&quot;&gt;hosted_posture.drain_posture().enabled&lt;/code&gt; before
making any call against the injected SaaS client — with drain off, the automatic hosted prereq
probe these startups would otherwise run is skipped outright, consistent with D-3’s “automatic
paths stay silent” rule rather than surfacing a probe failure.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D-4 / C-006 — Keep &lt;code dir=&quot;auto&quot;&gt;[sync].server_url&lt;/code&gt;’s name.&lt;/strong&gt; Its rename is a separate, out-of-scope
follow-up; this mission does not touch the key name.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D-5 — The personal activation file is the runtime-root &lt;code dir=&quot;auto&quot;&gt;config.toml&lt;/code&gt;.&lt;/strong&gt; Resolved by
&lt;code dir=&quot;auto&quot;&gt;specify_cli.paths.get_runtime_root()&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/config.toml&lt;/code&gt; on POSIX,
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt;-overridable — the same file that already carries &lt;code dir=&quot;auto&quot;&gt;[sync].server_url&lt;/code&gt;. This is
&lt;strong&gt;not&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;~/.kittify/config.toml&lt;/code&gt;, where &lt;code dir=&quot;auto&quot;&gt;[moments]&lt;/code&gt; already lives; the two are deliberately
different files, and &lt;code dir=&quot;auto&quot;&gt;moments drain status&lt;/code&gt; prints the resolved absolute path of every file it
reads (including this one) so the distinction is never silent.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D-6 / FR-016 — Logged-in machines keep their endpoint.&lt;/strong&gt; A machine with a stored auth session
from before the packaged default was removed has that session’s &lt;code dir=&quot;auto&quot;&gt;issuer_url&lt;/code&gt; backfilled into
&lt;code dir=&quot;auto&quot;&gt;[sync].server_url&lt;/code&gt; by an upgrade migration when no endpoint is configured — read-only against
the session store, never for a retired first-party host, never overwriting an explicit value, and
never enabling drain on its own. A configured endpoint and an enabled drain are independent
facts.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;R-1 — No environment variable can enable drain, in either scope.&lt;/strong&gt; The only env vars
&lt;code dir=&quot;auto&quot;&gt;hosted_posture.drain_posture()&lt;/code&gt; itself consults as narrowers are the three folded into
&lt;code dir=&quot;auto&quot;&gt;moment_handlers_disabled_reason()&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_NO_MOMENT_HANDLERS&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SYNC_DISABLE&lt;/code&gt;,
and the deprecated alias &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SYNC_MINIMAL_IMPORT&lt;/code&gt; — any of which forces the effective
posture off even with both scopes on. &lt;code dir=&quot;auto&quot;&gt;[moments] agents = &quot;off&quot;&lt;/code&gt; is a &lt;strong&gt;separate, non-env-var&lt;/strong&gt;
axis: the global or per-repo &lt;code dir=&quot;auto&quot;&gt;[moments]&lt;/code&gt; config key (&lt;code dir=&quot;auto&quot;&gt;~/.kittify/config.toml&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;repo&gt;/.kittify/config.toml&lt;/code&gt;) that narrows which moments reach agent context. &lt;code dir=&quot;auto&quot;&gt;DrainPosture&lt;/code&gt;
itself does not read it — it is tracked independently, alongside drain’s own narrowers, by
&lt;code dir=&quot;auto&quot;&gt;moments drain status&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_drain_narrowers&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;cli/commands/moments.py&lt;/code&gt;) as a second axis that
can also block a moment even when drain is fully on. A per-repo &lt;code dir=&quot;auto&quot;&gt;.kittify/config.toml&lt;/code&gt; never
carries the personal drain activation either — only the runtime-root &lt;code dir=&quot;auto&quot;&gt;config.toml&lt;/code&gt; does (D-5).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;R-2 — Explicit endpoint configuration is not drain-enablement.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;.kittify/saas-auth.json&lt;/code&gt;
(its own token) and a &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SAAS_URL&lt;/code&gt; sourced from a committed &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; both count as
explicit operator configuration of &lt;em&gt;where&lt;/em&gt; hosted traffic would go, never as consent for it to be
sent automatically.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;R-3 — Drain gates all relay traffic, not auth or the tracker.&lt;/strong&gt; Every relay CLI command and MCP
relay tool — including operator-typed commands such as &lt;code dir=&quot;auto&quot;&gt;zeitgeist send/reply/outbox approve&lt;/code&gt; —
pre-flights &lt;code dir=&quot;auto&quot;&gt;require_drain(&quot;relay&quot;)&lt;/code&gt; before any credential read. &lt;code dir=&quot;auto&quot;&gt;auth login/logout/status/ whoami/doctor&lt;/code&gt; and tracker commands are gated only by whether an endpoint is configured, not by
drain.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;R-4 / FR-013 — The retired-target migration now deletes, it no longer rewrites (#4259).&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;m_4_0_0_retired_hosted_target&lt;/code&gt; previously &lt;em&gt;rewrote&lt;/em&gt; a saved &lt;code dir=&quot;auto&quot;&gt;config.toml [sync].server_url&lt;/code&gt;
naming the retired first-party address (&lt;code dir=&quot;auto&quot;&gt;https://app.spec-kitty.ai&lt;/code&gt;) to the packaged default;
endpoint opt-in (D-1..D-5, reversing #3980) removed that packaged default from the resolver
entirely, so rewriting to a live address here would silently point a machine that never
configured a hosted endpoint at one. The migration’s &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; now &lt;strong&gt;deletes&lt;/strong&gt; the stale key
instead and prints the same &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SAAS_URL&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;config.toml [sync].server_url&lt;/code&gt; setup
guidance an unconfigured explicit command would show — every other saved value is untouched.
A machine that already has &lt;code dir=&quot;auto&quot;&gt;team.spec-kitty.ai&lt;/code&gt; recorded from an earlier run of this same
migration (before this behavior change) is a distinct, explicitly-preserved case: it keeps that
value as explicit, opt-in configuration. Drain still defaults off in both cases, so no automatic
traffic follows from a configured endpoint alone.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The operator surface for the whole model is &lt;code dir=&quot;auto&quot;&gt;spec-kitty moments drain on|off|status [--repo] [--json]&lt;/code&gt;, which reads and writes exclusively through &lt;code dir=&quot;auto&quot;&gt;core.hosted_posture&lt;/code&gt; (never a second
config reader or writer) and reports the effective posture, both scopes’ values and source files,
active narrowers, the ledger-projection posture, and all four hosted-posture file paths — existing
or not.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A fresh install talks to no server.&lt;/strong&gt; With no endpoint configured and drain off by default,
neither &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SAAS_URL&lt;/code&gt; nor &lt;code dir=&quot;auto&quot;&gt;config.toml [sync].server_url&lt;/code&gt; need to be set for local work
— specify, plan, tasks, implement, lane transitions, decisions — to complete unaffected; the
committed lane and decision ledgers are unconditionally intact under every setting (FR-010).
“Zero network” here means no &lt;code dir=&quot;auto&quot;&gt;*.spec-kitty.ai&lt;/code&gt; / Team Kitty / Zeitgeist host is contacted; the
PyPI upgrade-check notice is explicitly out of this scope — it already has its own opt-out,
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_NO_UPGRADE_CHECK&lt;/code&gt; (C-007).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The #4311 coupling is closed by construction, not by a future patch (C-005).&lt;/strong&gt; #4311’s bounded
live-publish retry is not yet on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;; because the drain gate sits at the network edge
(&lt;code dir=&quot;auto&quot;&gt;transport.ZeitgeistClient.offer&lt;/code&gt;, the capability gateway, the relay CLI/MCP surfaces) rather
than at each call site that might someday retry, any future retry path inherits the same
drain-off clean-skip behavior automatically. A drain refusal is never a diagnostic-as-error and
is never retried.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Two independent opt-ins replace one implicit default.&lt;/strong&gt; An operator who wants live drain must
turn on both the repository scope and their own personal scope — there is no single switch, and
no environment variable can shortcut either one (R-1). This is a deliberate friction increase
over the pre-#3980-reversal behavior, in service of the “twice, explicitly” requirement in
#4971’s brief.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Forward references, not relitigated here:&lt;/strong&gt; renaming &lt;code dir=&quot;auto&quot;&gt;[sync].server_url&lt;/code&gt; (D-4) stays a separate
follow-up issue; retiring the &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt; residue is likewise deferred except
where a future change happens to touch the same lines. This ADR records only what this mission
shipped.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendments&quot;&gt;Amendments&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Amended by &lt;a href=&quot;/adr/4.x/2026-10-13-2-the-event-ledger-is-the-publication-seam-default-on-with-local-retention/&quot;&gt;ADR 2026-10-13-2&lt;/a&gt;&lt;/strong&gt; (the event ledger is the publication seam, on by default). D-1 keeps its meaning, but the drain gate moves off the &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt; fan-out seam onto the Zeitgeist handlers, so a local adapter on the seam fires with drain off. D-2 is unchanged and gains a &lt;code dir=&quot;auto&quot;&gt;ledger.retention&lt;/code&gt; sibling for the gitignored local logs.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
