Plan managed Pi provider lifecycle

allod-agent commented

2026-08-20 16:48:31 +01:00

Member

This plan uses the existing Age/agenix and Pi command-helper path instead of creating another credential store.
It defines add, retarget, rotate, retire, and interruption recover operations on Nexus.
Retirement removes only owned Pi entries and orphaned ciphertext; unrelated user configuration remains.
Provider metadata belongs to profiles, while credentials, targets, and recipients belong to secrets.
Agents sharing the target VM account can still access the runtime credential; this plan does not claim otherwise.
Remote token revocation remains a provider-specific human step after verification from a fresh Pi process.
Merging this plan changes no running machine, credential, provider, package, or generated configuration.
Implementation remains blocked until the owner approves this revision with go.

Refs allod/strategy#34

Design

Empty public provider and credential registries preserve buildable synthetic templates without publishing live integration data.
A provider belongs to exactly one credential globally; credentials may be shared across providers only with one target set.
Retargeting requires re-entry so Age can encrypt to a new recipient set without decrypting the old ciphertext.
A durable non-secret journal and unchanged Git heads support path-scoped recovery without reset --hard or plaintext backups.
Archetypes owns Pi-compatible locking, ownership-based reconciliation, missing-secret no-op behavior, empty-desired cleanup, and fresh-process rotation verification.
Deploy observes and sabotages all profiles/secrets/inventory source bindings; inventory validates the Nexus host workspace from raw machine data.
The current private integration is not migrated or deleted by this public work. A later private rollout owns that one-shot cutover and real-provider verification.

Risk

R0 for this documentation-only PR. The planned implementation remains R3 because it crosses authentication, Age recipients, generated activation, persistent Pi configuration, six repositories, and host-operated lifecycle tooling.

Validation

Reconciled the design with a sanitized, no-decryption structural audit of the existing private mechanism.
First R3 review (gpt-5.6-sol, high) found and drove fixes for revision binding, credential cardinality, crash recovery, provisioning absence, Pi locking/cache behavior, retargeting, workspace availability, ownership, and unnecessary extension scope.
Final scoped review (gpt-5.5, high) found two witness-contract gaps; 9d639c9 now specifies the required composition observation APIs and raw-hypervisor inventory check.
The final review handoff is recorded in df34a4e; remaining uncertainty is assigned to executable implementation witnesses rather than another prose pass.
The plan is 127 lines and git diff --check passes.
No implementation, secret read/decryption, private mutation, deployment, or live-provider request was performed.

This plan uses the existing Age/agenix and Pi command-helper path instead of creating another credential store. It defines `add`, `retarget`, `rotate`, `retire`, and interruption `recover` operations on Nexus. Retirement removes only owned Pi entries and orphaned ciphertext; unrelated user configuration remains. Provider metadata belongs to profiles, while credentials, targets, and recipients belong to secrets. Agents sharing the target VM account can still access the runtime credential; this plan does not claim otherwise. Remote token revocation remains a provider-specific human step after verification from a fresh Pi process. Merging this plan changes no running machine, credential, provider, package, or generated configuration. Implementation remains blocked until the owner approves this revision with `go`. Refs allod/strategy#34 ## Design - Empty public provider and credential registries preserve buildable synthetic templates without publishing live integration data. - A provider belongs to exactly one credential globally; credentials may be shared across providers only with one target set. - Retargeting requires re-entry so Age can encrypt to a new recipient set without decrypting the old ciphertext. - A durable non-secret journal and unchanged Git heads support path-scoped recovery without `reset --hard` or plaintext backups. - Archetypes owns Pi-compatible locking, ownership-based reconciliation, missing-secret no-op behavior, empty-desired cleanup, and fresh-process rotation verification. - Deploy observes and sabotages all profiles/secrets/inventory source bindings; inventory validates the Nexus host workspace from raw machine data. - The current private integration is not migrated or deleted by this public work. A later private rollout owns that one-shot cutover and real-provider verification. ## Risk R0 for this documentation-only PR. The planned implementation remains R3 because it crosses authentication, Age recipients, generated activation, persistent Pi configuration, six repositories, and host-operated lifecycle tooling. ## Validation - Reconciled the design with a sanitized, no-decryption structural audit of the existing private mechanism. - First R3 review (`gpt-5.6-sol`, high) found and drove fixes for revision binding, credential cardinality, crash recovery, provisioning absence, Pi locking/cache behavior, retargeting, workspace availability, ownership, and unnecessary extension scope. - Final scoped review (`gpt-5.5`, high) found two witness-contract gaps; `9d639c9` now specifies the required composition observation APIs and raw-hypervisor inventory check. - The final review handoff is recorded in `df34a4e`; remaining uncertainty is assigned to executable implementation witnesses rather than another prose pass. - The plan is 127 lines and `git diff --check` passes. - No implementation, secret read/decryption, private mutation, deployment, or live-provider request was performed.

allod-agent added 1 commit

2026-08-20 16:48:31 +01:00

plan managed Pi provider credentials a3a39c34ef

allod-agent commented

2026-08-20 16:49:21 +01:00

Author

Member

Read-only review found two plan defects to fix before owner approval:

[GAP] The proposed Pi auth.check can only prove that the managed path exists; it cannot prove the file is non-empty or single-line. That would let pi auth check report the managed source for a broken credential. Omit the shortcut and have the normal resolver read/validate the runtime file for credential-free status checks and requests.
[GAP] “Reject non-bearer-token input” is not an executable boundary. Pin the accepted RFC 6750 b64token alphabet and trailing-padding rule so a quote/newline cannot turn the curl config stdin into additional directives.

Both are original-plan defects. The fixes should stay within the existing design and need no scope expansion.

Read-only review found two plan defects to fix before owner approval: 1. `[GAP]` The proposed Pi `auth.check` can only prove that the managed path exists; it cannot prove the file is non-empty or single-line. That would let `pi auth check` report the managed source for a broken credential. Omit the shortcut and have the normal resolver read/validate the runtime file for credential-free status checks and requests. 2. `[GAP]` “Reject non-bearer-token input” is not an executable boundary. Pin the accepted RFC 6750 `b64token` alphabet and trailing-padding rule so a quote/newline cannot turn the curl config stdin into additional directives. Both are original-plan defects. The fixes should stay within the existing design and need no scope expansion.

allod-agent added 1 commit

2026-08-20 16:49:47 +01:00

tighten Pi credential validation plan 79ca83c3a8

allod-agent commented

2026-08-20 16:50:01 +01:00

Author

Member

Addressed both review findings in commit 79ca83c:

Token input now has an exact RFC 6750-compatible grammar, closing curl-config injection ambiguity.
The generated provider omits the shallow auth-check shortcut, so pi auth check and real requests both read and validate the Age-backed runtime credential while returning only its source label.

A scoped review of that follow-up found no new inconsistency; the PR remains documentation/design only.

Addressed both review findings in commit `79ca83c`: - Token input now has an exact RFC 6750-compatible grammar, closing curl-config injection ambiguity. - The generated provider omits the shallow auth-check shortcut, so `pi auth check` and real requests both read and validate the Age-backed runtime credential while returning only its source label. A scoped review of that follow-up found no new inconsistency; the PR remains documentation/design only.

vnprc force-pushed agent/pi-provider-plan from 79ca83c3a8 to be44135c39

2026-08-20 20:20:11 +01:00

Compare

allod-agent commented

2026-08-20 20:23:53 +01:00

Author

Member

Owner review request: add an explicit old-token retirement lifecycle.

The plan should distinguish two operations:

Local retirement is automatable: after the Age-managed provider passes pi auth check and a real request, a Nexus-side command should atomically remove only that provider's stale API-key entry from the target VM's ~/.pi/agent/auth.json, without reading or displaying its value and without a force bypass.
Remote revocation is provider-specific: OpenAI-compatible inference defines request authentication, not token-management APIs. The tool must state whether rotation is overlap or in-place, print the correct order, and leave actual provider-side revocation/expiry to the owner rather than pretending a generic retire command can perform it.

The intended canary is therefore: enroll the existing token, rebuild and verify the managed path, retire the old local Pi entry, use the token normally, then issue and rotate to a replacement; revoke the previous remote token after verification when the provider supports overlap.

Owner review request: add an explicit old-token retirement lifecycle. The plan should distinguish two operations: 1. Local retirement is automatable: after the Age-managed provider passes `pi auth check` and a real request, a Nexus-side command should atomically remove only that provider's stale API-key entry from the target VM's `~/.pi/agent/auth.json`, without reading or displaying its value and without a force bypass. 2. Remote revocation is provider-specific: OpenAI-compatible inference defines request authentication, not token-management APIs. The tool must state whether rotation is `overlap` or `in-place`, print the correct order, and leave actual provider-side revocation/expiry to the owner rather than pretending a generic `retire` command can perform it. The intended canary is therefore: enroll the existing token, rebuild and verify the managed path, retire the old local Pi entry, use the token normally, then issue and rotate to a replacement; revoke the previous remote token after verification when the provider supports overlap.

allod-agent added 1 commit

2026-08-20 23:02:46 +01:00

revise Pi provider lifecycle plan a32d545087

allod-agent commented

2026-08-20 23:16:01 +01:00

Author

Member

Read-only R3 review of commit a32d545 with gpt-5.6-sol at high effort found ten plan defects:

[BLOCKER] The deploy graph could let secrets and archetypes validate against different inventory revisions.
[BLOCKER] The schema allowed one provider to resolve to different credentials on disjoint targets while rotate and retire selected a singular credential.
[BLOCKER] Ordinary rollback did not cover process death or power loss between mutations in the profiles and secrets repositories.
[BLOCKER] Missing Age material during provisioning was specified to abort instead of leaving reconciliation unchanged for a later activation.
[BLOCKER] The reconciler's unspecified lock would not necessarily coordinate with Pi's proper-lockfile auth writer.
[GAP] Pi caches command-backed auth for the process lifetime, so an already-running Pi session can retain the old token after rebuild.
[GAP] Adding a provider to a shared credential with a different target set named no executable retarget/rekey path.
[GAP] The public Nexus workspace does not currently include the profiles checkout required by the command.
[QUESTION] The plan did not distinguish exclusive ownership of managed JSON IDs from preservation of unrelated/operator-owned state.
[SIMPLIFY] Generic extension-link management added lifecycle surface while integration-specific extensions are out of scope.

These are original-plan defects. The follow-up should bind all shared inputs, require global provider-to-credential uniqueness, add durable crash recovery and explicit retargeting, use Pi-compatible auth locking, tolerate provisioning absence without mutation, require a fresh Pi process after rotation, declare managed-ID ownership, add profiles to Nexus inventory, and delete extension management.

Read-only R3 review of commit `a32d545` with `gpt-5.6-sol` at high effort found ten plan defects: 1. `[BLOCKER]` The deploy graph could let secrets and archetypes validate against different inventory revisions. 2. `[BLOCKER]` The schema allowed one provider to resolve to different credentials on disjoint targets while `rotate` and `retire` selected a singular credential. 3. `[BLOCKER]` Ordinary rollback did not cover process death or power loss between mutations in the profiles and secrets repositories. 4. `[BLOCKER]` Missing Age material during provisioning was specified to abort instead of leaving reconciliation unchanged for a later activation. 5. `[BLOCKER]` The reconciler's unspecified lock would not necessarily coordinate with Pi's `proper-lockfile` auth writer. 6. `[GAP]` Pi caches command-backed auth for the process lifetime, so an already-running Pi session can retain the old token after rebuild. 7. `[GAP]` Adding a provider to a shared credential with a different target set named no executable retarget/rekey path. 8. `[GAP]` The public Nexus workspace does not currently include the profiles checkout required by the command. 9. `[QUESTION]` The plan did not distinguish exclusive ownership of managed JSON IDs from preservation of unrelated/operator-owned state. 10. `[SIMPLIFY]` Generic extension-link management added lifecycle surface while integration-specific extensions are out of scope. These are original-plan defects. The follow-up should bind all shared inputs, require global provider-to-credential uniqueness, add durable crash recovery and explicit retargeting, use Pi-compatible auth locking, tolerate provisioning absence without mutation, require a fresh Pi process after rotation, declare managed-ID ownership, add profiles to Nexus inventory, and delete extension management.

allod-agent added 1 commit

2026-08-20 23:16:06 +01:00

resolve Pi lifecycle plan review findings 734a9fecf3

allod-agent added 1 commit

2026-08-20 23:16:35 +01:00

record Pi lifecycle review pass one 382e6ec3a2

allod-agent commented

2026-08-20 23:22:27 +01:00

Author

Member

Final scoped plan review (gpt-5.5, high effort) found two implementation-changing gaps in 734a9fe:

[GAP] The revision-graph contract requires an explicit archetypes API change. The current public framework exposes only profilesSource and composedLayerCheck { pkgs, expectedProfiles }; implementation must extend or replace that interface so the deploy canary compares the composed profiles, secrets, and inventory sources, including secrets.inputs.inventory.follows, and sabotages each redirect.
[GAP] The current inventory registry witness cannot prove the Nexus host receives the profiles checkout because it reads guest-only scripts/vm-specs.json, which excludes hypervisors. Implementation must add a host-workspace witness over machines.nexus.repos (or an equivalent raw-machine surface) and require exactly the lifecycle command's declared Nexus repository set.

Stable: public/private source split; global provider-to-credential uniqueness and explicit retarget; durable journal and path-scoped recovery; Pi-compatible locking, managed-ID ownership, missing-secret no-op, empty-desired cleanup, and fresh-process verification; no generic extension lifecycle.

Final scoped plan review (`gpt-5.5`, high effort) found two implementation-changing gaps in `734a9fe`: - `[GAP]` The revision-graph contract requires an explicit `archetypes` API change. The current public framework exposes only `profilesSource` and `composedLayerCheck { pkgs, expectedProfiles }`; implementation must extend or replace that interface so the deploy canary compares the composed profiles, secrets, and inventory sources, including `secrets.inputs.inventory.follows`, and sabotages each redirect. - `[GAP]` The current inventory registry witness cannot prove the Nexus host receives the profiles checkout because it reads guest-only `scripts/vm-specs.json`, which excludes hypervisors. Implementation must add a host-workspace witness over `machines.nexus.repos` (or an equivalent raw-machine surface) and require exactly the lifecycle command's declared Nexus repository set. Stable: public/private source split; global provider-to-credential uniqueness and explicit retarget; durable journal and path-scoped recovery; Pi-compatible locking, managed-ID ownership, missing-secret no-op, empty-desired cleanup, and fresh-process verification; no generic extension lifecycle.

allod-agent added 1 commit

2026-08-20 23:23:34 +01:00

specify Pi composition and host workspace witnesses 9d639c93ad

allod-agent added 1 commit

2026-08-20 23:24:11 +01:00

record Pi lifecycle review pass two df34a4ee89

1. [GAP] Composition observation: the three-input claim lacked public source-observation APIs and four independent follows sabotages; fixed by 9d639c9. Origin: introduced by 734a9fe. Issue: #34
2. [GAP] Nexus workspace witness: the existing registry check excluded hypervisors through its guest-only projection; fixed by 9d639c9. Origin: introduced by 734a9fe. Issue: #34

SIMPLIFY sweep: extension management remains deleted; no additional whole mechanism can be removed without losing add, retarget, rotate, retire, or recovery.

Model: gpt-5.5

allod-agent changed title from ~~Plan managed Pi provider credentials~~ to Plan managed Pi provider lifecycle

2026-08-20 23:24:57 +01:00

allod-agent commented

2026-08-20 23:25:04 +01:00

Author

Member

Resolved the final scoped review findings in 9d639c9:

Secrets now exports its consumed inventory source; archetypes exposes all four composed source observations; deploy binds and independently sabotages archetypes profiles/secrets/inventory plus secrets-inventory follows redirects.
Inventory validation now reads raw machine data so hypervisors are covered. Every Nexus hypervisor requires profiles, secrets, and inventory, while the public fixture proves the only workspace addition is profiles.

The review handoff in df34a4e records this as the second and final R3 plan-text pass. The other pass-1 fixes survived unchanged. Remaining questions are executable and belong to the implementation witnesses after owner approval.

Resolved the final scoped review findings in `9d639c9`: - Secrets now exports its consumed inventory source; archetypes exposes all four composed source observations; deploy binds and independently sabotages archetypes profiles/secrets/inventory plus secrets-inventory follows redirects. - Inventory validation now reads raw machine data so hypervisors are covered. Every Nexus hypervisor requires profiles, secrets, and inventory, while the public fixture proves the only workspace addition is profiles. The review handoff in `df34a4e` records this as the second and final R3 plan-text pass. The other pass-1 fixes survived unchanged. Remaining questions are executable and belong to the implementation witnesses after owner approval.

vnprc merged commit df34a4ee89 into master

2026-08-21 02:54:15 +01:00

vnprc deleted branch agent/pi-provider-plan

2026-08-21 02:54:15 +01:00

Rows
Columns

Plan managed Pi provider lifecycle #35

Design

Risk

Validation