@topolo/cli 0.13.17 → 0.13.21

package/README.md

@@ -537,10 +537,24 @@ exchanges the stored refresh token for a new pair before making the request
 and rewrites the config — no user action required. The OAuth `client_id` used
 at login is persisted alongside the credential so refresh can re-authenticate.
 
-If refresh fails (network, rotated/revoked refresh token), the CLI proceeds
-with the stale credential and the request returns `auth_error` — run
-`topolo auth login` to re-authenticate. The stored config is not cleared on
-transient refresh failures.
+If refresh fails for a transient reason (network, a 5xx, a rate limit), the
+saved grant is kept and the request fails with a retryable error; a rate limit
+reports `rate_limited` with `retryAfter`, and the CLI never retries a refresh
+on its own.
+
+If Auth refuses the grant (`invalid_grant` or `expired_token`), the saved
+sign-in has ended. It is removed once, under the config lock, and is never sent
+again by any process, so a dead sign-in cannot use up the token endpoint's
+failure limit for everything else on the machine. One shared device
+re-authorization is started for that environment and context, and then:
+
+- **At a terminal**, the CLI opens the approval page, prints its URL and code,
+  waits for approval and continues the command with the new credential.
+- **Anywhere else** (no terminal, `CI` set, or `TOPOLO_NO_REAUTH_PROMPT=1`), the
+  command exits with code 2 and a structured `reauth_required` error that
+  carries the approval link, user code, expiry and the equivalent
+  `topolo auth login` command. The device code is never printed. Approve the
+  link (or run the login command) and the next command continues.
 
 ## Topolo Agent Packs
 

package/agent-packs/README.md

@@ -415,7 +415,60 @@ transport applies and reads back those settings. UI automation is not part of
 the adapter. Import status is deliberately separate from native activation proof.
 ### Experimental Claude live configuration
 
-The native import is not pack activation. `configure` can preflight and apply
+Fresh coordinator `configure` now uses capability discovery in the running
+app's loaded native modules. It does not admit a particular app version or
+bundle filename. Engineering, Operator and CI/CD are pinned automatically by
+the acknowledged native sidebar command during this settings phase. Saved
+`isStarred` metadata alone is insufficient. Missing or changed capabilities,
+native refusals and unmatched readbacks stop setup with a durable journal.
+`startup-settings` is an explicit alias for this settings phase.
+
+The settings result keeps `packActivated` and `cloudDispatchVerified` false.
+Native import, startup permissions, successful task execution, cloud task
+authority, live Activity and retirement are separate acceptance boundaries.
+The worker adapter now binds native SDK terminal receipts to the exact input,
+SDK session and selected model. Retirement requires a verified cloud checkpoint
+and refuses a pinned worker, active work or an archive cascade into children.
+These capabilities do not by themselves activate the operational cloud broker.
+For a source-independent three-coordinator installation, successful native
+startup also installs the supported `UserPromptSubmit` and `PreToolUse` hooks
+using the actual attached SDK session IDs. The prompt hook uses Claude's native
+`prompt_id` to reserve one cloud task, then stops the coordinator turn before
+inference. Missing identity, an inactive cloud authority or a lost delivery
+acknowledgement blocks direct coordinator execution; no transcript is consulted
+and no replacement task is created.
+
+The Claude cloud service uses the existing GUI connection and ledger protocol.
+It creates single-use native sessions inside the already signed-in Claude
+Desktop process. Approved native setup installs an authenticated, owner-only
+local socket exposing the existing create, send, read and archive operations.
+The temporary setup debugger can then close. The connection exports neither
+vendor credentials nor arbitrary evaluation, and does not require CLI login.
+A tool-free readiness result,
+native model, bypass and effective-effort acknowledgements precede task input.
+Each phase loads one Agent specialization as `CLAUDE.md` and its selected cloud
+task packet. Progress, checkpoints and independent review use the same cloud
+events as Codex. Completed workers are archived through the native Desktop
+session manager only after independently verifying their cloud checkpoint.
+Lost acknowledgements preserve the owned session and refuse another delivery.
+The connection belongs to one Desktop process; a replacement process requires
+native setup and a new connection before dispatch. No local task ledger or
+chat history replaces the cloud authority. Startup refuses execution until
+the production Docs conditional-write contract and migrated dataset are active.
+
+`topolo agent-packs work serve-claude --harness claude` starts the owning service
+explicitly; installed front-door hooks start it on demand after verifying cloud
+activation. Its lifetime is bounded by the verified Desktop process. Setup
+preparation, source tests and hook installation are not a live dispatch proof.
+Task assignment has its own native boundary: it requires the exact tool-free
+readiness result and an acknowledged canonical cloud delivery reservation before
+sending the preallocated input UUID. Missing or lost acknowledgements retain
+that reservation for reconciliation; they never trigger another send.
+
+The older full-roster switch/recovery path described below retains its legacy
+compatibility qualification; it is not the fresh coordinator settings path.
+
+The native import is not pack activation. The legacy adapter can preflight and apply
 an already adopted roster through the running Claude main process. This is an
 internal compatibility adapter qualified for **Claude Desktop 2.31226.1** and
 the exact native module hashes in `src/lib/claude-pack-backend.ts`; it refuses
@@ -722,3 +775,418 @@ Only existing owned physical destinations inside the library can change. Shared
 Apply reserves `launchers/adoption-<UUID>.json` exclusively. The journal starts in `may-have-config-effects`, records each verified replacement, and becomes `configuration-prepared-native-adoption-unverified` only after all readbacks. Every write rechecks generation, source, profile metadata, preservation pins and destination custody. An interrupted or conflicting apply retains the journal and any uncertain temporary file; it never automatically replays or rolls back. Reconcile exact effects with the original owner.
 
 No apply result proves native reload, identity, current RBAC, model/effort, loaded context, original-intake permission routing or a native tool result. Hosts may react to configuration changes; admit the actual affected owner/generation and normal request settlement before applying in a live host. Later ordinary startup can renew the private credential and load identity. A previous 429/403 or scoped recovery hold remains separately applicable and elapsed time grants no retry. Actual Codex and Claude same-query context, permission, nonce result, cancellation/settlement and own retirement require independent native evidence.
+
+## Throughput and adaptive reasoning
+
+New task-model templates use revision 2. Codex chooses Luna/low only for an
+explicit `trivial`, low-risk `format`, `extract-fields`, `reference-lookup` or
+`status-read` task. Routine tasks use Sol/low (with medium as a declared effort
+alternative); standard tasks use Sol/medium; complex and security-critical
+tasks use Sol/high. Astra remains available only through an authorized explicit
+override. Unavailable models/efforts refuse rather than silently falling back.
+Existing installed configurations and fixed native sessions are not migrated by
+upgrading the adapter. Review and install a current `models-template`, then verify
+the actual native model/effort acknowledgement for every task. `low` is the native
+name for light reasoning.
+
+`topolo agent-packs lane allocate --input snapshot.json` returns a bounded,
+read-only allocation plan. The closed version-1 input contains `now` (epoch
+seconds), `maxAgeSeconds` (1–3600), actual execution `slots` (0–32),
+`maxNewLanes` (0–8), `tasks`, `lanes`, `completed`, `configuration` and `catalog`.
+The configuration/catalog use the existing task-model contracts. Each task has
+`id`, `capability`, `priority` (0 is highest), `owner` (lane ID or null),
+`dependencies` (completed task IDs), `authorized`, `paused` and `modelTask`.
+Each lane has `id`, `capabilities`, `observedAt`, `registryState`
+(idle/busy/held/paused/unknown), `nativeState` (idle/busy/unknown), `activeTask`
+(ID or null), `retainedTasks`, `reusableCheckpoint`, `assignments`,
+`lastAssigned` and its explicit model `constraints`.
+
+The allocator considers every compatible worker rather than preferring an
+ordinal. It chooses the least assigned, then oldest assigned worker; never
+moves an owned task; permits retained custody only at an explicit idle safe
+checkpoint; isolates stale/contradictory observations and blocked dependencies;
+and limits both existing work and proposed new lanes by supplied execution
+capacity. A worker receives at most one assignment per plan. The caller must
+supply trustworthy current observations; a timestamp in JSON does not prove
+native availability or admission.
+
+The result's snapshot digest must be checked by the canonical claim writer
+before an exclusive assignment. Each assignment includes its full model
+resolution with `nativeACK: null`. Create requests are proposals requiring the
+normal registered native lifecycle, not created agents or claims. This command
+does not claim, dispatch, wake, schedule, execute or retire anything. Native
+settings, authority, actual delivery and completion remain independently
+verified boundaries. In particular, it does not repair or establish a hidden
+cross-chat event transport by writing a file.
+
+Fresh-role `config.json` model/effort presets are retained in the captured agent
+manifest and used when compiling its Codex runtime policy. They do not revert
+to a legacy high-effort role default on activation. A missing preset keeps the
+legacy profile unchanged. Native catalog and exact settings readback still apply.
+
+### Individual role definitions and front-door dispatch
+
+`work-bind-roles --pack NAME --agent-workspace WORKSPACE` performs installation
+administration: it discovers Agent definitions and writes only IDs and instruction
+digests to `work/role-bindings.json`. Each definition has a unique
+`config.specialization.logicalId`, concise role-specific instructions, and matching
+`config.purpose`. Source authoring files are in `specializations/`; they are not a
+runtime export. Updating an existing published definition requires its supported
+draft lifecycle transition. This adapter reads the pinned definition; it does not
+claim that an edited definition has a newly published hosted-execution version.
+
+Each temporary worker fetches exactly one Agent ID, verifies its organization,
+workspace, logical role and instruction digest, and writes only that specialization
+to its new workspace (`AGENTS.md` for Codex, `CLAUDE.md` for Claude). Model
+constraints cover the configured harnesses; resolution still intersects the
+selected harness with its current native account catalog and refuses unavailable
+models. A separate pinned task context can reference one immutable
+Bytes JSON packet (`topolo-task-context-v1`, taskId, markdown). Assignment never
+reads the role export, Agent memory or prior chat history. Missing or changed
+bindings stop dispatch rather than borrowing another role's context.
+
+Enable `frontdoorDispatch: true` in the reviewed work configuration only after all
+three channel bindings and role/context references are qualified. Text requests
+from Engineering, Operator and CI/CD then become broker tasks before the
+coordinator receives an acknowledgement-only receipt. A native message ID provides
+idempotency; ambiguous retries and unbound attachments refuse. This is functional
+routing, not a new tool-permission sandbox. Existing direct coordinator turns are
+preserved and are never submitted again by enabling this feature.
+
+Activity projects task-ledger transitions and separately labels observed native
+coordinator activity. Observing an active or idle native chat does not establish
+business completion. Native lifecycle events persist these observations and wake
+the GUI event stream; a fresh GUI request can also reconcile the current status.
+Observation failures are exposed, not presented as verified live progress.
+
+Mutable cloud task authority remains a separate activation gate. Recovering an
+immutable evidence archive or fetching individual roles/context does not prove
+conditional cloud task ownership, safe machine takeover, or Claude Desktop native
+settings activation. Those boundaries require their own runtime acceptance.
+
+Pass `--bytes-workspace WORKSPACE` when binding installation roles to configure the
+reviewed production task-context workspace. A new request is queued immediately;
+its background dispatch publishes and reads back one small immutable request
+packet before starting a native worker, then persists that artifact reference on
+the existing task. Upload acknowledgement loss is retained as an uncertain receipt
+and is not replayed. Task context never silently falls back to a template tree.
+Native input arriving during the short acknowledgement turn (`turn/steer`) enters
+the same idempotent request path as `turn/start`.
+
+### Source-only Topolo installation
+
+The bundled `templates/topolo-coordinators` template creates exactly Engineering,
+Operator and CI/CD. It contains no native IDs, old work or specialist chats.
+Build it in a genuinely new installation store, then prepare cloud dispatch:
+
+```sh
+topolo-agent-pack --store /local/AgentPacks/installation build topolo-instance --template templates/topolo-coordinators
+topolo-agent-pack --store /local/AgentPacks/installation work-install --pack topolo-instance --agent-workspace AGENT_WORKSPACE --bytes-workspace BYTES_WORKSPACE
+```
+
+The version-2 specialization catalog contains only role metadata, Agent references,
+instruction digests and explicit task-model constraints. Engineering, operations
+and CI/CD have separate eligible disciplines and independent reviewers. A task
+worker inherits its currently owned coordinator's qualified permission profile,
+then receives the selected specialization and independently resolved task model;
+there is no captured-specialist runtime or source thread dependency.
+
+Preparation is not activation. This path requires the existing activated cloud
+work dataset and current organization-bound/native permission qualification.
+Missing cloud authority refuses before execution and never selects local history
+or SQLite as an alternative. A busy outgoing owner is preserved.
+
+
+## Destination account and native sidebar sections
+
+Portable packs carry role and group membership, not authority to use a captured
+account identity. Import creates native memberships without copying source
+account IDs into the destination sidebar. The ordinary switch/install verification
+reads the destination's native `account/read` response and binds the original
+sections to its `workspaceRouting.chatgptAccountId` when the account is ChatGPT.
+No credentials are parsed, copied or created by sidebar binding.
+
+A provider-only or signed-out profile reports `pending-sign-in`; a non-ChatGPT
+account reports `pending-chatgpt-account`; a ChatGPT response lacking the actual
+workspace ID reports `pending-account-identity`. These states do not mean the
+sidebar is installed or visible. After ordinary sign-in, repeat the same switch
+command: an unchanged composition refreshes only its destination presentation,
+without replacing agents or history. A managed window uses its existing native
+manager and checks the selected home, account and backend generation.
+
+`configured-rendering-unverified` means account-scoped settings were bound; it
+does not prove visible sections, provider transport or context/permission routing.
+Sidebar binding never changes model providers, models, effort, permissions or
+authentication mode. Genuine account/provider coexistence, manual/background/
+dynamic provider inheritance and actual transport still require qualification
+before changing live profile defaults.
+
+## Closed legacy cloud cutover
+
+`work-cloud-prepare-delta --source-store SOURCE --input REQUEST.json` prepares
+explicitly selected closed tasks against the destination's existing inactive
+Docs dataset and exact current version. The request contains `documentId`,
+`datasetId`, `expectedCurrentVersionId`, and `tasks` selectors with `taskId`,
+`revision`, and `artifactManifest` (null, or an exact path/SHA-256 manifest).
+The command preserves task and worker identities, blocked states and historical
+checkpoint hashes. It publishes only the selected request packet, final assistant
+outputs, normalized terminal receipts and explicitly declared artifact files to
+Bytes, then verifies their readback before a revision-checked local metadata
+transition. Native prompts, reasoning and tool histories are excluded. A bounded
+artifact manifest supports more files without loading them all into dispatch
+context. Original evidence references remain historical provenance, not fresh
+verification of external files. Durable upload receipts refuse uncertain replay.
+
+After all tasks and native workers are closed, upgrade the idle legacy proxy to
+the released source and request `work cutover`. This authenticated native barrier
+holds the broker lock, checks pending jobs and turns, fences SQLite writes inside
+its transaction and stops its native child. Its immutable ACK binds the process
+birth, root, executing guard source and final snapshot. An older running proxy
+cannot claim this contract. A failed stop leaves a fence requiring explicit
+recovery; it does not permit migration or resume writes.
+
+`--store DESTINATION work-cloud-cutover --source-store SOURCE --input REQUEST.json`
+requires that same ACK and an exact `documentId`, `datasetId`,
+`expectedCurrentVersionId`, and `sourceDigest`. It preserves the existing portable
+cloud rows, appends verified delta rows under their original IDs, checks the
+retained inventory digest, and activates that same Doc with one conditional
+version write. Every new context packet, checkpoint and result artifact is read
+back before activation. A durable intent and exact readback resolve a lost ACK
+without repeating the write. Neither command starts work or creates replacement
+tasks. Do not reactivate the fenced local broker after cloud activation.
+
+A fresh signed-in Claude installation can use the same startup entry point:
+
+```sh
+topolo agent-packs --store /local/AgentPacks/installation startup-settings PACK --prepare --pid CURRENT_PID --endpoint AUTHORIZED_LOOPBACK_ENDPOINT --apply
+```
+
+`--prepare` validates existing approved installation consent and current organization
+policy, prepares exactly the three coordinator records without opening CLI
+sessions, and writes a new policy artifact. Missing native coordinator identities
+are created through the signed-in Desktop session manager and must finish their
+own tool-free native readiness result before settings or pins are accepted.
+Prepared coordinator context uses role charters and policy rather than local
+conversation history. An unresolved startup journal prevents preparation.
+
+For an explicitly selected move from another installation, add
+`--previous-connection /previous/installation/claude/desktop-task-connection.json`.
+The old endpoint and its exact three bound coordinators must be quiescent. After
+successor settings, control and hook acknowledgements, startup unpins and archives
+only those old coordinators through acknowledged native APIs. Active work, child
+cascades, changed ownership or lost acknowledgements retain the recovery journal;
+they never trigger an automatic replay. Cloud activation and verified business
+work remain separate acceptance boundaries.
+
+## Attach another clean installation to the same task authority
+
+After the original migration activates its existing Docs dataset, a second
+clean installation can join that **same document and dataset**, with a distinct
+installation ID. Prepare its authored three-coordinator pack, organization-bound
+consent and `work-install` metadata first; do not copy task SQLite files or chat
+history, and do not reuse the fenced migration-source directory.
+
+```sh
+topolo agent-packs --store CLEAN_INSTALLATION work-cloud-attach --input REVIEWED_SELECTORS.json
+```
+
+The exact selectors are `pack`, `workspaceId`, `documentId`, `datasetId`,
+`installationId`, `expectedCurrentVersionId` and `expectedCatalogDigest`.
+Attachment freshly verifies the production principal, organization execution
+policy, selected current Docs version, activated dataset and local role catalog.
+It rejects an existing local ledger, native owner, unresolved operation or an
+installation ID already recorded in cloud tasks or workers. Foreign active work
+retains its owner. The operation writes only a private local binding and its
+exclusive recovery journal; it creates no cloud documents, tasks or workers and
+never adopts or resumes work. An exact verified replay reads back the same
+binding without rewriting it. A lost local acknowledgement can reconcile an
+already written exact binding; a missing or changed binding remains held without
+replay. Native execution refuses any incomplete attachment journal. Normal host
+startup and task dispatch remain separate, verified activation steps.
+
+
+## Reconnect the existing fenced Codex installation
+
+`work-cloud-migrate --input SELECTORS.json` prepares a read-only plan for the
+original installation whose closed SQLite ledger was migrated to an existing
+cloud dataset. This differs from clean-install attachment: it preserves its
+three existing coordinator keys and native IDs, including mixed-pack channels.
+Selectors are `installationId` (a fresh, distinct identity),
+`expectedFenceDigest`, `expectedMetadataDigest` and
+`expectedTargetCatalogDigest`. Apply the exact reviewed plan with
+`work-cloud-migrate --input PLAN.json --apply`.
+
+The operation verifies the immutable SQLite fence, source history, original
+target binding, canonical retained digest, current production identity and
+organization policy, selected Agent definitions and original native consent.
+It changes only local configuration, reviewed role references and cloud binding,
+with a durable partial-write hold. Cloud versions and task owners are recorded
+as observations; normal concurrent cloud work cannot invalidate a local-only
+attachment. All actual task mutations retain their existing cloud version and
+owner CAS checks. No task, worker, owner or local history is copied, rewritten,
+adopted or resumed by attachment. The legacy ledger remains fenced permanently.
+Admission rechecks the exact metadata and selected channel-role closure before
+using the original coordinator as the worker's permission source. Starting the
+attached installation never automatically adopts another installation's work.
+
+
+Fresh Claude readiness startup uses the native workspace-trust manager for only
+its exact approved directory, with literal-key trust and current context/consent
+checks. It does not trust a parent directory or dismiss a trust dialog by UI.
+If an interrupted three-coordinator bootstrap left only its first creation
+attempt, `topolo agent-packs --store ROOT startup-settings PACK --endpoint URL
+--pid PID --reconcile` independently checks all three native identities,
+transcripts and pending starts. It never sends input. Only verified absence can
+retire the startup marker into the retained audit; arbitrary earlier filesystem
+effects remain UNKNOWN. Any existing session, history, active start, changed
+context or later journal effect keeps the hold. Start normally only after that
+explicit reconciliation receipt; do not remove the marker by hand.
+
+For an older installation that predates frontdoor bindings, an explicit
+`--previous-library /exact/old-profile/library` reads its existing private
+coordinator-adoption proof and three original identity records. Their file
+hashes stay bound throughout startup. Native idle/ownership checks happen
+before fresh readiness starts. After successor settings, pins, hooks and task
+control are acknowledged, the existing native retirement path unpins and
+archives only those three old identities. Active work, changed proof, children
+or lost acknowledgements preserve the hold; no UI pinning or replacement
+metadata is used.
+
+If readiness creation was acknowledged but the SDK has not yet published its
+session identity, the reader waits on the exact queued input; terminal results
+still require the matching SDK identity. An interrupted readiness-only operation
+can use `startup-settings PACK --continue-readiness --policy ORIGINAL_POLICY
+--endpoint CURRENT_ENDPOINT --pid CURRENT_PID --apply` with the same previous
+connection/library selectors. This retains its original journal, context and
+preallocated IDs. Existing probes are verified without resending input; only
+previously uncreated coordinator identities may start. Unknown starts, changed
+context, business input or later settings effects refuse continuation.
+
+The native cloud authorizer uses a qualified host Python 3.11+ executable,
+independent of Desktop's inherited PATH. Its absolute regular executable, byte
+digest and exact version are bound into native control qualification and checked
+before each authorization child; no application environment or account changes.
+
+Managed Claude startup retains both identity-bearing profile roots. Before native
+startup, `startup-settings PACK --launch-desktop --policy POLICY
+--desktop-profile EXISTING_DESKTOP_DIRECTORY --claude-config-dir EXISTING_CODE_DIRECTORY
+--apply` launches through macOS LaunchServices with the exact SDK environment,
+or discovers the already owned profile process. It never copies authentication
+or history and does not stop another profile. A private exclusive launch receipt
+prevents duplicate launches after a lost acknowledgement. The subsequent normal
+startup verifies the current native user-data directory and SDK root before any
+session or settings changes. App versions are discovered rather than pinned.
+
+When an acknowledged readiness probe survived an app restart but its ephemeral
+SDK terminal did not, explicit original-operation continuation can adopt only
+its exact persisted fixed user/READY exchange, selected model/settings and
+unchanged role context after independently proving the original process dead.
+It records `originalTerminalUnknown: true`; it does not reconstruct a terminal
+receipt or resend the probe. Only this installation readiness exchange can use
+the history adoption path. The native manager then warms the same existing SDK
+session without model input, and settings/process identity are read back before
+startup proceeds. Pending/held work, another input, tools, changed identity or
+uncreated IDs with history preserve the hold. Business worker completion still
+requires the original matching SDK terminal and lifecycle evidence.
+
+If readiness, pins, effective settings and the native task-control installation
+were acknowledged but front-door hook installation failed, use the original
+operation's `startup-settings PACK --complete-startup --policy ORIGINAL_POLICY
+--endpoint CURRENT_ENDPOINT --pid CURRENT_PID --apply` (and the original
+`--previous-library` when present). This checks the existing three idle probe
+sessions and control identity, consumes the unchanged original front-door input,
+finishes idempotent hooks and then retires the exact old coordinators. It never
+creates sessions, resends readiness, reapplies models or repins. Any later work,
+changed settings/context, missing ACK or uncertain retirement keeps the hold.
+Hook installation has a bounded ten-minute budget for the selected cloud reads;
+failed attempts retain private error-code/status and stderr-digest diagnostics.
+
+After the same three coordinators have completed their cloud dispatch, review,
+Activity and archival qualification, finalize their original startup with
+`topolo agent-packs --store ROOT startup-settings PACK --finalize --policy POLICY
+--startup-operation ORIGINAL_UUID --qualification-task COMPLETED_TASK_UUID
+--endpoint OWNED_LOOPBACK_ENDPOINT --pid OWNED_PID --allow-native-debugger-menu --apply`. This independently
+reads the current cloud task/checkpoints and native session identities before
+journaled adoption of metadata. It never imports, copies or resends a conversation.
+The completed startup journal and original unknown terminal evidence remain intact.
+
+Subsequent `startup-settings PACK --launch-desktop --policy POLICY --apply` uses
+the recorded signed-in profile and same three Desktop/SDK identities. It reports
+ready only after the closed native control and owning cloud dispatcher answer.
+A cold start verifies the predecessor is dead and every installation-owned worker
+is closed before temporary loopback inspection restores connect-only native
+control. Inspection closes on success and failure; uncertain launch or metadata
+ACKs retain their journal and prohibit replay. An active metadata file alone is
+never operational acceptance. The Electron inspector capability is discovered
+and verified against the actual PID/profile; no application build is pinned.
+
+With explicit launcher-only menu authorization, cold restoration discovers the
+unique enabled, unchecked native “Enable Main Process Debugger” checkbox in the
+exact owned macOS process. It requires a free loopback9229 endpoint, uses only
+that vendor capability, then verifies the actual PID and Desktop/SDK profile
+before native control restoration. The temporary inspector closes afterward.
+There are no guessed startup flags, SIGUSR1, fuse changes, application patches,
+pin/archive UI actions or account copying. Absent/disabled/ambiguous native
+capability or unresolved workers retain their existing ownership and audit.
+
+An approved setup can upgrade only the closed native task-control implementation
+without touching coordinator sessions or task inputs:
+
+```sh
+topolo agent-packs --store INSTALLATION startup-settings PACK --upgrade-control \
+  --startup-operation ORIGINAL_STARTUP_UUID --policy ORIGINAL_POLICY \
+  --endpoint CURRENT_APPROVED_LOOPBACK_ENDPOINT --pid CURRENT_DESKTOP_PID --apply
+```
+
+This requires the completed original three-coordinator startup, unchanged owned
+context and bindings, a stopped dispatcher, and zero native workers. It preserves
+all startup and unresolved-effect evidence, sends no native input, and closes the
+temporary inspector even on refusal. Recover an already-delivered uncertain
+completion with `work-recover-claude-completion --harness claude --input REQUEST`
+only under its exact reviewed worker/output manifest; this never resends work.
+
+If a cold launch stopped before any control installation, retain its journal and
+use `startup-settings PACK --launch-desktop --continue-launch ORIGINAL_UUID
+--policy ORIGINAL_POLICY --endpoint CURRENT_APPROVED_ENDPOINT --pid CURRENT_PID
+--apply`. This accepts only the original single-row pre-control journal, an
+independently dead predecessor, unchanged identities, closed historical workers
+and the exact already launched profile. It never launches another application,
+creates coordinators or resends input. Any later or ambiguous journal retains
+custody and refuses this continuation.
+
+A cold launch that has already acknowledged its exact native control and hooks,
+but failed before service readiness, uses the same `--continue-launch` selector.
+The launcher validates that journaled control, private secret, original predecessor,
+installed hook bindings and three unchanged SDK identities. It requires the former
+service process to have exited and its lifetime lock to be free, then independently
+verifies the current control is idle before ensuring the service and completing
+metadata. It does not repeat connect-only calls, control installation, hooks,
+coordinator creation or input. Unknown or later journal stages remain held.
+The dispatcher closes its accepted watch connections before awaiting server
+shutdown, so a connected Activity view cannot keep a dead Desktop's owner alive.
+
+`topolo agent-packs --store ROOT desktop-launcher` installs the distinct
+Topolo Agent Pack application for that Codex installation. Use its own icon:
+generic ChatGPT, Personal or Work icons can open another profile. Opening the
+pack icon restores its exact live managed process without restarting the backend
+or replaying active work; a cold open uses the existing guarded launcher.
+
+
+## Coordinator conversation and specialist assignments
+
+The three pinned coordinators converse with the human on their existing native
+model. Each prompt receives bounded current-channel cloud task heads and the
+qualified installation's broker command. Status, follow-ups and clarification
+create no task automatically; the original input and attachments remain intact.
+For an actual assignment, the coordinator reconciles existing work and explicitly
+uses the task broker with the supplied deterministic native-message request ID.
+Implementation and operational effects stay with task-based specialists.
+
+Claude's coordinator hook permits owned context reads and a single typed request
+file, plus foreground bundled broker commands for reads, dispatch and responses.
+It denies direct shell engineering, source edits and other agent mechanisms.
+`work wait --input REQUEST.json` reads an existing task until a canonical change
+or terminal result, with exact task/cursor selectors and a 1–30 second bound.
+It never submits, adopts, reruns or changes work. Coordinators inspect those real
+results and answer in their native conversation; a queue acknowledgement or GUI
+link alone does not satisfy the human request.

package/agent-packs/coverage_changed.py

@@ -15,7 +15,7 @@ from coverage.parser import PythonParser
 
 RELEASE_BASE = '6a13ada56844712aae58738ba01dbbdf90718bef'
 SOURCE = pathlib.Path('agent-packs/src/topolo_agent_pack')
-MODULES = {'topolo', 'claude', 'policy', 'permissions', 'approvals', 'execution', 'live', 'cli', 'lanes', 'task_models'}
+MODULES = {'topolo', 'claude', 'policy', 'permissions', 'approvals', 'execution', 'live', 'cli', 'lanes', 'task_models', 'throughput'}
 
 
 class CoverageRefused(RuntimeError):

package/agent-packs/docs/selected-artifacts.md

@@ -0,0 +1,47 @@
+# Selected legacy task artifacts
+
+`work-cloud-prepare-delta` preserves the existing task and worker IDs, closed
+native receipts, source digests and unresolved outcomes. It does not start work
+or activate a dataset. Original archived files and checkpoints are never edited.
+
+An existing worker-local artifact manifest remains a list of `{path, sha256}`
+rows with optional `bytes`. Select its exact original path and SHA-256 in the
+task selector's `artifactManifest`. All reviewed evidence must be represented,
+except the separately normalized original native checkpoints.
+
+When necessary reviewed evidence lives outside the worker workspace, prepare a
+new selection file in an owned evidence directory, without changing the worker's
+original manifest. Its shape is:
+
+```json
+{
+  "format": "topolo-selected-task-artifacts-v1",
+  "taskId": "<the existing task>",
+  "workerId": "<its existing execution worker>",
+  "artifacts": [{"path": "<exact source file>", "sha256": "<exact SHA-256>"}]
+}
+```
+
+The selection is bound by its own path and digest. An outside-workspace artifact
+is eligible only when its exact path and digest already occur in that task's
+reviewed evidence. This does not grant access to an arbitrary directory. Files
+must remain owned, single-link, non-symlink ordinary files with unchanged bytes
+and no group/world write permission. Missing or changed historical sources fail
+explicitly; no fallback or invented copy is accepted.
+
+If the live original path has advanced, an explicit selection may add
+`contentPath` to a row already present in the task's reviewed evidence. It names
+an owned immutable archive inside the selected manifest's directory. Its bytes
+must match the **original reviewed SHA-256** exactly. The original `path` and
+hash remain the evidence identity, with the archive path recorded separately.
+This permits verified historical bytes without overwriting another owner's live
+file. There is no automatic fallback, changed-hash acceptance or history upload.
+
+The read-only `cloud_delta.selected_artifacts(task, workers, selector)` preflight
+checks the whole selection before any upload. The delta command preflights every
+selected task before preparing cloud context. A TASK-CONTINUATION.json packet
+must belong to the same task; each absolute file reference in its proof mapping
+must be explicitly selected and hash-verified. Native checkpoints, JSON/JSONL
+session histories, prompts and reasoning are refused as artifacts. The portable
+manifest retains original source paths and hashes alongside each verified cloud
+artifact reference. Existing task/claim/intent custody and effects remain unchanged.

package/agent-packs/documentation/cloud-task-state.md

@@ -0,0 +1,56 @@
+# Cloud task continuity
+
+Topolo Agent supplies reusable specialization. Task records, owner/effect
+identities, checkpoints and evidence belong in Docs and Bytes. A native chat is
+an execution surface, never the task authority.
+
+## Evidence recovery
+
+`topolo agent-packs work-recover --reference recovery-reference.json --destination NEW_DIRECTORY`
+
+The small portable reference identifies an organization-scoped Bytes archive
+and its compressed and uncompressed hashes. The command downloads it using the
+currently authenticated production organization credential, verifies every file,
+and restores content-addressed objects and a path index. It never restores old
+absolute paths, native transcripts, credentials, a dispatch database, or worker
+ownership. Missing original files remain explicit. The destination must be new.
+This command does not read an existing AgentPacks library.
+
+Evidence recovery establishes continuity of the snapshot. It does not establish
+that remote work is currently active, that every source checkout can be rebuilt,
+or that a held/UNKNOWN operation can safely be repeated.
+
+## Mutable cloud ledger (release-gated)
+
+`cloud_work.CloudStore` requires the published Docs conditional-version contract
+(`expectedCurrentVersionId`) and bounded current-state reads (`includeHistory`).
+Do not enable it against an older catalog. It uses one Docs-selected generation
+and an immutable Bytes retained inventory. Each operation reads the current
+generation and conditionally publishes the next. A conflicting write is refused;
+a lost acknowledgement is reconciled once by the exact operation identity.
+Unavailable cloud state never falls back to local SQLite.
+
+Both `work/config.json` authority `topolo-docs` and a complete `work/cloud.json`
+binding must be installed together. The selected cloud body must explicitly be
+activated. A prepared migration snapshot grants no execution authority. The
+installation identity is unique: startup cannot adopt another installation's
+workers, and dispatch skips tasks owned elsewhere. Continuation uses the existing
+task identity after terminal-worker reconciliation and explicit checkpoint adoption.
+
+The active document is bounded to 900,000 characters. Archival beyond that limit
+is not implemented; reaching the limit refuses further writes visibly. This is
+not a claim of an unlimited production task service.
+
+## Activation acceptance
+
+Before cutting over: quiesce the current owner, preserve a matching final
+snapshot, verify the published production guard with a real competing-writer
+test, verify exact task/context/evidence identity from an empty installation,
+and reconcile all current native workers. Install the cloud authority fence
+before allowing dispatch. Validate request idempotency, lost-response recovery,
+foreign-owner refusal and live GUI activity. Do not mark migration complete on
+the basis of unit tests or an evidence-only restore.
+
+Claude Desktop settings/adoption require their own native acknowledgement.
+Writing CLI settings or importing a seed is not proof of Desktop bypass mode,
+model selection, specialist dispatch or successful execution.

package/agent-packs/domain-contexts/README.md

@@ -0,0 +1,25 @@
+The CI/CD operating reference is an existing private Docs runbook, separate from
+role instructions and current task state. `cicd.json` records its reviewed immutable
+version and selected heading. Put this reference in `config.domainContextRefs`
+(as a one-element array) on the existing CI/CD coordinator and its five specialist
+Agent definitions through their supported draft lifecycle. Keep
+`config.specialization` limited to format, logicalId and instructions, with purpose
+matching instructions.
+
+Installation discovery binds these exact references alongside each role's
+instruction digest. It refuses CI/CD definitions without one reviewed reference.
+Every selected role materialization fetches and validates that immutable Docs
+version and heading before native startup, even when an existing task packet is
+cached. Only the selected section enters `context/release-controller.md`; no old
+task history or whole runbook is injected. The Docs transport can return bounded
+version history because the released get contract has no separate exact-version
+read. The resolver limits history to128 versions, the selected body to1MB and the
+selected section to12KB; it refuses a missing pinned version instead of using a
+newer version silently.
+
+Current authority endpoints, access bindings, fleet state and exact release IDs
+belong in the task's existing Docs/Bytes packet. The runbook identifies supported
+read interfaces; it does not grant credentials, transfer ownership or authorize
+mutations. Updating source authoring files alone does not change hosted Agent
+records or activate the Desktop launcher. Review, native readback and normal
+source release remain separate gates.