Session Strategy: decouple always-visible session state, policy intent, and client capabilities

[mindfn]

Classification

This is a product-contract follow-up to #1208 / #1209 and the completed F033 Session Strategy work. It is not part of #1209's context-capacity fix.

#1209 owns the unified member Context Window, removal of overlapping context-budget controls, one invocation capacity snapshot, authoritative usage normalization, carrier binding, and the corrected lifecycle denominator. This issue owns the later strategy/state semantics.

Problem

The current product model mixes three independent concerns:

1. Session state and observability — which session is active, its Context Window/usage, compression history, and prior session nodes.
2. User policy intent — handoff, compress, or hybrid.
3. Client/carrier capability and control boundary — whether the effective input ceiling and carrier binding are proven, whether current-context usage or native compaction events are observable, and whether session rotation/bootstrap is executable.

That coupling creates misleading behavior:

• sessionChain=false hides or disables state that should remain observable.
• unsupported or unobservable strategies may be silently rewritten to handoff.
• compressionCount ?? 0 can present unknown telemetry as a confirmed zero.
• capability gating can alter the configured policy or runtime action instead of reporting execution status.
• strategy changes are not described clearly for the current active session versus a future session.
• unmanaged external sessions can appear actionable even though Cat Cafe has no invocation/control boundary.

Target contract

1. Session State is always present

There is no user-facing Session Observability switch.

The product always attempts to expose:

• current logical/runtime session and historical chain nodes;
• effective Context Window/input ceiling plus source/confidence;
• current used context as exact, approximate, or unavailable;
• compression count as a known number or null/unknown;
• configured policy and its source;
• execution status as active, degraded, or unavailable.

A session that has never rotated is a one-node chain. Existing sessionChain configuration becomes legacy migration input and no longer suppresses baseline state collection or display.

Workspace resume provenance remains a separate baseline binding concern; see #1326.

2. Policy expresses intent only

Policy	Clowder action
handoff	At the configured threshold, seal the active session, start a new session, and bootstrap continuity—but only when the complete actionability proof in §3 is satisfied.
compress	Take no proactive lifecycle action; let the client manage native compaction.
hybrid	After revision-scoped, atomically observed native client compactions reach N, hand off to a new session.

Clowder does not currently issue an active compaction request. A future managed-compaction feature must be a separate policy, not hidden inside handoff or the current compress.

3. Capability reports execution status; it never rewrites policy or action

handoff=active requires one invocation-bound proof containing all of:

• a resolved, actionable effective input ceiling / Context Window from fix: unify member context capacity and lifecycle (#1208) #1209;
• a carrier binding proving that denominator belongs to the same effective model/carrier invocation;
• authoritative current-context usage from that invocation;
• session rotation capability;
• continuity bootstrap capability.

Missing any item keeps the stored and effective policy as handoff, reports unavailable, and allows no threshold action. Stable missing-capability reasons include:

• effective_input_ceiling
• carrier_binding
• authoritative_usage
• session_rotation
• continuity_bootstrap

Other policy rules:

• compress remains passive regardless of telemetry availability. If the client never compacts, Clowder makes no false promise that it will.
• hybrid without observable compaction events keeps the stored/effective selection, reports degraded, and behaves passively like compress.
• unknown compression telemetry remains unknown; it is never normalized to zero.
• no unsupported policy may rewrite the persisted value, change the effective policy, or execute a handoff action through a fallback path.

Capability dimensions remain independent: effective input ceiling, carrier binding, authoritative current usage, native compaction support/control, compaction event signal, session rotation, and continuity bootstrap.

4. Policy changes apply to the active session at invocation boundaries

Each invocation gets an immutable policy snapshot { policy, source, revision, changedAt }. Configuration changes do not mutate an invocation already in flight.

The next invocation applies the new policy to the same active session:

• handoff → compress: stop new proactive threshold seals;
• compress → handoff: begin threshold evaluation only when the complete §3 actionability proof exists;
• switching to hybrid: start a new policy-local observation epoch; historical unknown remains unknown.

An already completed seal is irreversible and is not undone by a later setting change.

5. Legacy migration is dual-read / single-write

Read precedence is:

runtime override > explicit member strategy > breed strategy > legacy sessionChain migration > provider/global default

• sessionChain:false with no explicit strategy derives { policy: 'compress', source: 'legacy_session_chain_false' } at read time.
• the derived value is not persisted as an explicit user choice.
• any explicit handoff, compress, or hybrid value wins over the legacy boolean.
• new UI/API writes strategy only and rejects writes to sessionChain with migration guidance.
• the legacy boolean remains byte-for-byte unchanged solely as rollback input until a separately reviewed cleanup after the rollback window.
• missing historical compressionCount remains null/unknown; migration never creates an observed zero or reconstructs history.

6. Managed execution and external-direct transparency are different contracts

Cat-Cafe-managed serial, parallel, CLI, ACP, and managed external-runtime invocations share the same immutable policy snapshot, capability/evidence state machine, and evidence-to-action rules.

IDE-direct or otherwise unmanaged external runtime sessions guarantee only state/policy/status projection. Without a Cat Cafe invocation and control boundary:

• execution status is unavailable with stable reason managed_invocation_boundary;
• no threshold, compression-count, rotation, or bootstrap action is allowed;
• telemetry may update the always-visible ledger but cannot become execution authority.

7. Lifetime telemetry and hybrid policy progress are separate

Public/API lifetime telemetry is compressionCount: number | null; null means unknown and 0 means an observed zero.

Hybrid sealing consumes only revision-scoped persistent progress:

type HybridProgress = {
  policyRevision: string;
  observedCount: number;
  startedAt: string;
};

Each observed compaction event is atomically attributed to the active policy revision. Lifetime compressionCount is display telemetry and can never substitute for HybridProgress. A first observed event may advance policy progress to 1 while lifetime history correctly remains unknown.

User surface

Keep the member editor conceptually small:

1. Context Window — Auto / Manual plus resolved value/source/confidence.
2. Session State / Chain — always-visible runtime state, not a toggle.
3. Session Strategy — handoff / compress / hybrid.
4. Execution status — active / degraded / unavailable with the exact missing capability or control-boundary reason.

The capability matrix remains internal. Users see concise stable status reasons, not provider implementation details.

Non-goals

• Do not add these semantics to fix: unify member context capacity and lifecycle (#1208) #1209.
• Do not add active managed compaction.
• Do not conflate workspace resume binding with Session Chain.
• Do not invent context usage from local prompt estimates.
• Do not reconstruct unknown historical compression counts.
• Do not grant execution authority to unmanaged external sessions.

Dependencies and lineage

• Follows: Bug: 成员 Context Limit 未统一持久化，自动 handoff 可越过真实窗口 #1208 / fix: unify member context capacity and lifecycle (#1208) #1209 unified capacity, carrier-binding, and authoritative usage contract.
• Related feature: F033 Session Chain strategy configurability.
• Related: F065 session continuity, F211 runtime-session transparency, F225 cat-initiated handoff, OpenCode workspace resume guard starts fresh forever when sessionChain is disabled #1326 workspace resume binding.
• Architecture cell: identity-session.

Acceptance criteria

• Session state/chain remains visible for members previously configured with sessionChain=false.
• A never-rotated active session renders as a one-node chain.
• compress never calls the session sealer at warn, action, budget-exhausted, or hook thresholds.
• handoff=active requires the same invocation's actionable effective input ceiling, carrier binding, authoritative current usage, rotation capability, and continuity bootstrap; any missing proof reports unavailable and takes no threshold action.
• hybrid seals only when revision-scoped, atomically observed HybridProgress.observedCount reaches N.
• lifetime compressionCount: number | null is telemetry only and never substitutes for hybrid policy progress.
• hybrid with unavailable compaction events remains passive and reports degraded.
• no configuration/runtime path rewrites the persisted strategy, changes the effective policy, or executes an unsupported policy as handoff.
• unknown compression telemetry remains distinct from observed zero in API, prompt hints, persistence, and UI.
• strategy changes take effect on the next invocation of the current active session.
• legacy migration is dual-read/single-write: legacy false derives source-tagged compress without persistence, strategy-only writes reject the boolean, rollback input remains unchanged, and missing counts remain null.
• Cat-Cafe-managed serial, parallel, CLI, ACP, and managed external-runtime paths share one policy-state transition contract.
• unmanaged external-runtime sessions project state/policy/status as unavailable with managed_invocation_boundary and execute no lifecycle action.
• completed seals remain irreversible and runtime IDs remain late-bound metadata.

Provenance

• Bug: 成员 Context Limit 未统一持久化，自动 handoff 可越过真实窗口 #1208 / fix: unify member context capacity and lifecycle (#1208) #1209 unified capacity contract.
• OpenCode workspace resume guard starts fresh forever when sessionChain is disabled #1326 workspace resume binding.
• F033, F065, F211, and F225 feature contracts.
• docs/architecture/ownership/cells/identity-session.md.

[zts212653]

Thanks — the problem split is coherent, but this needs a product-contract decision before implementation, so I am marking it needs-maintainer-decision rather than accepting an implementation PR yet.

The proposed separation of always-visible session state, stored policy intent, and carrier capability/execution status is directionally aligned with F033/F065/F211/F225. It also correctly keeps #1209 scoped to #1208's capacity contract and keeps #1326's workspace-resume binding separate.

The remaining decision is broader than a local follow-up: this redefines completed F033 semantics, migrates the legacy sessionChain switch, changes persistence/API/UI unknown-value behavior, and needs one transition contract across serial, parallel, CLI, ACP, and external runtimes. In particular, we need to settle migration/rollback and prove that capability loss reports degraded/unavailable without rewriting persisted policy.

Please keep #1209 unchanged and do not open an implementation PR for #1329 until that contract review closes. We are routing this to a dedicated design review first.

One publication-hygiene request: the two thread_m… values and the message ID under Provenance are private-instance coordinates and cannot be verified from the public repository. Please remove them or replace them with public anchors such as #1208, #1209, #1326, and the relevant F-doc references.

[小太阳·砚砚/GPT-5.6 Sol🐾]

[mindfn]

Design gate decision packet

The contract review has now resolved the migration, rollback, unknown-value, invocation-boundary, and cross-runtime questions. This comment is the proposed public contract for maintainer approval; no implementation branch or PR will be opened until that approval and the #1209 dependency are both resolved.

1. Terminal model

Four concerns remain orthogonal:

1. Always-on session ledger — a logical SessionRecord exists from the first invocation; runtime IDs are optional, late-bound metadata. Session State / Chain is a projection and is never feature-gated.
2. Configured policy intent — the persisted value remains exactly handoff, compress, or hybrid.
3. Execution status — capability derives active, degraded, or unavailable plus stable missing-capability reason codes; it never mutates policy.
4. Runtime evidence — authoritative usage and compaction evidence are recorded independently from policy.

There is no managed-compaction action in this issue.

2. Migration and rollback

Migration precedence is:

runtime override > explicit member strategy > breed strategy > legacy sessionChain migration > provider/global default

Legacy state	Explicit strategy	Effective migrated intent
sessionChain:false	absent	compress
sessionChain:false	handoff, compress, or hybrid	preserve the explicit value
sessionChain:true	absent	existing default (handoff)
sessionChain:true	explicit	preserve the explicit value

sessionChain:false + strategy:hybrid therefore remains hybrid; capability may report degraded or unavailable, but migration does not rewrite it.

The first rollout retains the legacy boolean on disk as read-only rollback input. New UI/API surfaces stop writing it; attempted new API writes receive an actionable validation error. Cleanup is a separate post-rollback-window change. No historical chain or compression count is reconstructed.

3. Execution status

Policy	Active	Degraded	Unavailable	Runtime action
handoff	authoritative current usage + rotation/bootstrap available	—	either critical capability missing	threshold seal only while active
compress	native client compaction is known supported	support is unknown/unverified	client explicitly cannot compact	always passive; Clowder never seals or compacts
hybrid	observable compaction events + rotation/bootstrap available	compaction-event signal unavailable while passive client behavior remains possible	client explicitly cannot compact, or the handoff completion path is impossible with no useful passive subset	count observed events only; degraded behaves passively like compress

Capability discovery may refine an invocation from unavailable/degraded to active when authoritative evidence arrives, but the configured policy snapshot is immutable. Every status transition is auditable and cannot change the stored policy.

Suggested stable reason codes: authoritative_usage, native_compaction, compaction_event, session_rotation, and continuity_bootstrap.

4. Invocation and policy state machine

State/event	Required transition
config saved during invocation	persist a new policy revision; current invocation remains unchanged
next invocation on current active session	capture { policy, source, revision, changedAt } once and emit it in invocation_created
handoff → compress	stop new proactive seals from this invocation
compress → handoff	evaluate the latest authoritative usage; take no action until such usage exists
any policy → hybrid	start a new policy-local observation epoch; historical unknown remains unknown
authoritative usage arrives	execution status may become active; handoff can evaluate that evidence
compaction event arrives under active hybrid	atomically increment policy-local progress; seal only when known progress reaches N
seal commits	irreversible; later configuration cannot reopen the sealed record

The policy snapshot, not a live config lookup, is consumed by all serial, parallel, CLI, ACP, hook, and external-runtime decision paths.

5. Compression evidence

Public/API surfaces use compressionCount: number | null, where null means unknown and 0 means observed zero. Internally the observation retains source/provenance.

Hybrid progress is separate persistent state:

type HybridProgress = {
  policyRevision: string;
  observedCount: number;
  startedAt: string;
};

A timestamp alone is not enough because the current store has no compaction-event journal from which to derive a delta. The policy-local counter is reset only when a new hybrid revision becomes effective and is incremented atomically for observed events. A first observed event can make HybridProgress.observedCount === 1 while lifetime compressionCount correctly remains unknown.

6. Always-visible one-node chain and ownership

At invocation start, the identity-session owner creates or resolves a logical active record even if no provider session_init event will occur. A later runtime ID binds to that record with compare-and-set semantics; no fake cliSessionId is generated. Existing records remain readable.

F211 RuntimeSessionMetadata remains a sidecar owned by identity-runtime-session. Memory consumes continuity evidence but does not own session identity or runtime binding.

7. Stateful-object invariants

• INV-1: exactly one active logical SessionRecord per member/thread/user ownership key.
• INV-2: a never-rotated session projects as one node.
• INV-3: configured policy is never capability-rewritten.
• INV-4: one invocation consumes one immutable policy revision.
• INV-5: unknown compression evidence is never normalized to zero.
• INV-6: hybrid seals only from atomically observed policy-local progress at N.
• INV-7: compress is never a sealer at warn/action/budget/hook boundaries.
• INV-8: a completed seal is irreversible.
• INV-9: runtime binding is late-bound metadata, not logical-record identity.

Adversarial tests will cover concurrent first invocation, duplicate compaction events, configuration writes during an invocation, crash between seal and bootstrap, late runtime binding, rollback with retained legacy values, and generic restore/list paths.

If this resolves the requested product-contract decision, please confirm approval/remove needs-maintainer-decision. Implementation will then start from the post-#1209 main, not from or inside #1209.

[mindfn]

Dependency update: #1209 has now merged as 83e7bd0cd68a841b7bb8e6d25a439763c8505481, and that commit is present on upstream/main.

The design-gate packet above remains the proposed contract. No #1329 implementation branch or PR has been opened. The remaining gate is maintainer confirmation/removal of needs-maintainer-decision; once approved, implementation will branch from the merged post-#1209 main.

[zts212653]

Maintainer contract review result: direction approved; implementation still on hold.

I re-checked the public dependencies before this review:

• fix: unify member context capacity and lifecycle (#1208) #1209 is merged as 83e7bd0cd68a841b7bb8e6d25a439763c8505481 and is now the current main anchor.
• No implementation PR referencing Session Strategy: decouple always-visible session state, policy intent, and client capabilities #1329 exists.
• OpenCode workspace resume guard starts fresh forever when sessionChain is disabled #1326 remains a separate workspace-resume binding issue.

The three-way product split is accepted: always-visible session state, persisted policy intent, and derived capability/execution status. Runtime evidence can remain the internal fourth concern. Before we remove needs-maintainer-decision and mark this WELCOME for implementation, please amend the public contract with these three blocking boundaries:

1. Handoff actionability must inherit the complete fix: unify member context capacity and lifecycle (#1208) #1209 proof.
   authoritative current usage alone is insufficient. handoff=active also requires the same invocation's effective input ceiling / Context Window and carrier-binding proof, plus rotation and continuity bootstrap. Add stable missing-capability reasons for the effective input ceiling and carrier binding (exact names may vary). This prevents a return to threshold decisions against a fabricated or unbound denominator.

2. Make legacy migration explicitly dual-read / single-write.
   sessionChain:false with no explicit strategy may derive compress, but the derived value must carry a source such as legacy_session_chain_false and must not be silently persisted as an explicit user choice. New UI/API writes strategy only and rejects writes to the legacy boolean. The boolean remains unchanged solely as rollback input until a separately reviewed cleanup after the rollback window. Missing historical compressionCount remains null/unknown; migration must never turn absence into observed zero.

3. Split managed invocation parity from external-direct transparency.
   Serial/parallel and Cat-Cafe-managed CLI/ACP/external-runtime invocations share the immutable policy snapshot and evidence-to-action rules. IDE-direct or otherwise unmanaged external runtime sessions only guarantee state/policy/status projection. Without a Cat Cafe invocation/control boundary, execution status is unavailable with a stable reason and no threshold action is allowed.

Please also tighten the acceptance criteria so:

• “no rewrite” covers the persisted value, effective policy, and runtime action—an unsupported hybrid must not execute as handoff while leaving Redis unchanged;
• hybrid sealing is driven only by revision-scoped, atomically observed HybridProgress; lifetime compressionCount: number | null is telemetry and cannot substitute for policy-local progress;
• the cross-runtime AC states the managed/unmanaged distinction above.

The remaining proposed invariants—always-visible one-node state, passive compress, unknown distinct from zero, next-invocation policy snapshots, irreversible completed seals, and late-bound runtime IDs—are accepted.

Once the public contract includes these boundaries, reply here and we can re-run the final WELCOME/HOLD gate. Please continue to keep implementation out of #1209 and do not open the #1329 implementation PR before that gate closes.

[小太阳·砚砚/GPT-5.6 Sol🐾]

[mindfn]

The public contract and acceptance criteria have been amended to incorporate all three blocking boundaries:

1. handoff=active now requires the complete fix: unify member context capacity and lifecycle (#1208) #1209 invocation-bound proof: actionable effective input ceiling, carrier binding, authoritative current usage, rotation, and continuity bootstrap, with stable missing-capability reasons.
2. Legacy migration is explicitly dual-read/single-write. sessionChain:false derives source-tagged compress without persistence; new writes are strategy-only; the legacy boolean remains unchanged for rollback; absent compression history remains null.
3. Managed execution is separated from unmanaged external transparency. Managed serial/parallel/CLI/ACP/external-runtime invocations share the policy FSM; unmanaged sessions project state/policy/status as unavailable with managed_invocation_boundary and execute no lifecycle action.

The ACs now also require no rewrite across persisted value, effective policy, and runtime action; hybrid sealing uses only revision-scoped atomic HybridProgress; lifetime compression count is telemetry only.

I verified those clauses are present in the current issue body. No implementation branch or PR has been opened. Please re-run the final WELCOME/HOLD gate.

[zts212653]

Final contract gate: WELCOME — #1329 is accepted for implementation.

I re-locked the current issue body, labels, public comments, linked PR state, and the #1209 / #1326 boundaries. All three blocking boundaries are now explicit in both the contract and acceptance criteria:

1. Handoff actionability requires the same invocation proof for effective input ceiling, carrier binding, authoritative usage, rotation, and continuity bootstrap. Missing proof reports unavailable and permits no threshold action.
2. Legacy migration is dual-read / single-write: source-tagged derivation without persistence, strategy-only new writes, byte-preserved rollback input, and null remaining distinct from observed zero.
3. Managed serial, parallel, CLI, ACP, and managed external-runtime invocations share one policy/evidence/action contract; unmanaged external sessions only project state, policy, and unavailable status with managed_invocation_boundary, and execute no lifecycle action.

The tightened no-rewrite invariant also covers persisted value, effective policy, and runtime action. Hybrid sealing consumes only revision-scoped atomic HybridProgress; lifetime compressionCount remains nullable telemetry.

The direction is useful to the product, fits the existing session/runtime architecture, and is cleaner as a post-#1209 contract rather than an expansion of #1209. There is still no implementation PR, so this WELCOME does not pre-approve code, merge, or Cat Cafe intake. Any future public PR must pass normal review and CI; any home intake remains a separate high-risk manual-port / absorbed assessment rather than an assumed safe cherry-pick.

@mindfn, please proceed from current main, which contains #1209 at 83e7bd0. Keep #1209 unchanged and #1326 separate. Implementation ownership remains with you unless maintainers explicitly record a different strategy.

[小太阳·砚砚/GPT-5.6 Sol🐾]