Repository navigation
[TWS-01] Refresh read-only topology and authoritative thread context #9
Description
ID: TWS-01 (F-003). Priority: P1. Blocked by: #2. Backlog: #1.
Problem and existing boundary
The fork has a read-only TWS adapter and opaque workspace/feature/stack-node
bindings, but not adapter-driven refresh or thread-to-feature association.
Project membership alone cannot assign a feature: several features can share
one project. Repository grouping is never routing or association authority.
Current decoder reports preserve raw feature/entry objects. Add the narrow
typed normalization needed for association from the public version-pinned
CLI output; do not pretend those raw arrays are already a safe topology model.
Scope
On-demand, environment-owned TWS refresh and persisted thread context, exposed
through bounded typed commands/queries. Context contains scoped opaque
workspace/feature and optional stack-node binding IDs, source/evidence,
material revision and freshness. Keep logical feature association separate
from the currently materialized execution node.
Association rules
- Only the owning environment resolves its filesystem/Git execution location.
Do not trust a remote client-supplied path or use another host's path rules. - Filter matching to the correct environment and parent workspace/feature.
Repository/name-only locators cannot establish a thread association.
A conflicting strong identity yields ambiguity, not a weaker-locator match. - Workspace context requires one verified project/workspace association.
Multiple candidates remain ambiguous until an explicit valid choice. - Feature context requires an existing explicit server-validated choice, or a
unique exact execution-node match that proves its parent feature. Do not
assign every feature which mentions the same project. - Stack-node context additionally requires a unique exact current project,
canonical checkout/worktree and branch association. Branch alone, missing
materialization or an archived node does not establish a current stack node. - Explicit set/clear/reassign operations change only T3 context, require a
material revision and validate membership. They do not move a checkout,
select a provider or mutate TWS. Changing location invalidates current-node
evidence; it does not silently rewrite explicit logical feature choice. - Stable opaque IDs survive proven renames. When only a name/path locator
changed and identity continuity cannot be proved, require confirmation;
do not merge because the display label resembles the previous feature.
Refresh and freshness
- Trigger on explicit refresh, initial relevant view/reconnect, an existing
trustworthy topology-change signal, or a T3 execution-context change.
Coalesce concurrent requests. No periodic CLI polling/watch daemon. - A refresh has a server-issued observation ID and coverage per workspace and
feature. Completeness requires successful public enumeration of that scope,
decoded required association fields, supported versions and no truncation.
A row-limited repository query or raw partially decoded report is not proof
that omitted entities are gone. - Preserve valid partial positives only for independently complete scopes.
Missing fields, failed commands, ambiguity, unsupported versions and output
limits yield unavailable/degraded scope with last-known data, never empty
authoritative success. - Observation freshness is "last confirmed", not a claim of real-time watching.
Existing trusted filesystem invalidation may mark stale; age alone never
revokes a context or tag. No observer events means no invented currentness. - Successful refreshes advance observation evidence; only material context
changes advance context revision. Use bounded delta/query summaries and lazy
detailed provenance; never leak full registry paths to aggregate shell lists.
Acceptance criteria
Cover multiple features in one project, multiple workspaces, multi-repository
features, conflicting locators, duplicate names/branches across hosts, checkout
changes, renamed/moved sources, archived/unmaterialized nodes, explicit
set/clear/reassign, partial/truncated scans and stale refresh completion.
Older refresh generations cannot overwrite a newer observation.
Preserve read-only exact-version TWS behavior and opaque environment identity.
A project can appear in its existing repository group without a confident TWS
association. No failure may hide the physical project or infer provider state
from TWS agent_state.
Coverage and non-goals
Server/contracts for all clients and providers; local and remote routes
unchanged. Minimal context commands are shared by later web/mobile surfaces.
No grouping UI, derived tags, TWS mutation, process liveness inference,
worktree creation or automatic cross-environment merging.
Activity
jdbencardinop commentedon Oct 1, 2026
Maintainer-approved addition: TWS is an optional integration, off by default per environment. Disabling makes no TWS CLI calls, cancels owned scans and leaves saved choices inactive; re-enable requires fresh observation. Clear is a persistent opt-out until explicitly returning to auto. Context edits use revision/incarnation/location guards. The pinned public stable_id is path-derived, so registry marker identity proves workspace moves; feature/node renames need explicit reassignment where continuity is unproved. No plugin framework, TWS mutation or polling.
jdbencardinop commentedon Oct 1, 2026
TWS-01 completed locally
Current verified branch:
phase2/tws-context.f8988b45cfd0743b3db4611295dfd642957d47c3.8d9d7314b88097afaf5d7c37a85fab206f71aeb9.76e281e194df533d8bcece9349a84a34bfbfa6a0.982929e9323f00ded5c7ca943f22a0bcef669a6f.Optional integration
TWS is off by default, separately for each environment, with a switch in
Settings -> Integrations. Disabled requests do not invoke TWS; disabling cancels
the owned scan and hides cached TWS state without discarding saved choices.
Re-enabling requires fresh observation. No generic plugin framework was added.
The pinned v1.2.14 tool remains a read-only external dependency. Its public
registry/status/stack fields were checked against pinned source and actual
read-only CLI output. Each refresh re-probes the version. The public report's
stable_id is path-derived; persistent registry marker identity proves workspace
moves. Feature/node name-only changes require explicit reassignment.
Context and refresh
The environment alone resolves canonical Git execution location. Logical
workspace/feature choice is separate from current-node evidence. Branch names,
repository grouping, provider hints and TWS agent_state never establish an
association. Unsupported cross-repository, archived and unmaterialized nodes
remain unassociated.
Explicit set/reassign uses an expected material revision and validates
membership. Clear is a persistent opt-out until returning to automatic mode.
Thread/project incarnation and location guards prevent stale choices from
crossing entity recreation or checkout changes. No checkout, provider or TWS
mutation is performed.
One owned scan and bounded queued invalidation coalesce refreshes. CLI work
happens outside database transactions; generation and metadata checks prevent
stale completion. Commits use the latest saved choices, so refresh cannot undo
a concurrent clear. Fresh observations update evidence, not material revisions.
Partial scopes retain last-known data and independently complete positives;
failed or limited reads never become authoritative empty success.
Fork migration 49 adds TWS observation/context storage and compact topology
summaries, retaining existing binding tables. A partial creation-event index
supports efficient incarnation checks. Public pages are bounded to 100 rows and
a 60 KiB entry budget; full locator paths are lazy single-binding provenance.
Five typed authenticated RPCs and shared client-runtime exports support later
web/mobile consumers. Grouping UI and derived tags remain #10/#14.
Evidence
read-only adapter/version refresh, disabled bypass/cancellation, coalescing,
ambiguity, partial data, parent identity/rename rules, pagination, explicit
clear/auto, concurrent edits, incarnation changes, disk reopen, migration
compatibility, settings and authorization.
and denial without orchestration-read scope.
lint and production web build passed.
disabled, explicit opt-in, read-only commands, fresh-version rejection,
visible unavailability, disable persistence and reload staying disabled.
the installed read-only TWS tool. No TWS workspace was modified. A command-
scoped synthetic login-shell PATH then isolated the final fixture pass; no
user shell configuration or global PATH was changed.
Maintenance and limits
Foundation retains its complete 98-path intent. Client attention was replayed
on the updated parent, with exact whole-product equality against the tested
integration tree. The previous branch and failed metadata attempts remain
preserved; no historical failures were relabeled.
Tpatch v0.16 retained two old generated preimage hashes during recipe refresh.
The final deterministic recipe was generated from actual parent bytes and
tested postimages, independently checked, then genuinely recorded and landed.
All six maintained roots verify and the DAG has zero violations.
No branch push, PR, live T3 database write, provider turn, TWS mutation or new
native-package qualification. Native Windows can use a WSL environment for
pinned TWS; the T3 app itself remains independent of TWS.
Owned test processes, disposable data and temporary replay worktrees were
cleaned up; selected UI evidence remains session-local.
#10 is now ready. #14 still waits for #11. This is also a suitable source
snapshot for fresh Mac/Windows packaging; the older platform qualification
does not automatically cover these new features.
Implemented with GPT-6 Astra through GitHub Copilot CLI; no delegated inference.