Share a managed token profile across agents

CLI/PHP 0.1.3 coordinates token lifecycle operations across processes that use the same local app, grant, profile and keychain directory. Install the verified release on every participating worker before sharing that profile. Token/PHP remains storage-neutral and the CLI still requires token-php >=0.1.3 <0.2.0.

Upgrade existing workers

  1. Stop workers that loaded an older CLI implementation.
  2. Download the CLI/PHP 0.1.3 ZIP, SHA-256 checksum and manifest, verify the checksum, and extract into its own version directory.
  3. Point every worker at the same updated CLI and the intended token library. Check m7-identity --version reports 0.1.3.
  4. Keep the existing protected keychain and select the app/profile explicitly. Restart workers with the updated code. An upgrade does not require a new device authorization or copying tokens between profiles.

Use the same keychain directory for processes sharing one grant. An independent host or separately copied store needs its own authorized grant or an application coordinator that spans those machines. Filesystem locking in one store cannot coordinate another store.

Renewal and safe contention

One process owns selection, renewal, complete pending checkpoint, ACK and active promotion. Other processes cannot dispatch a competing lifecycle for that profile. They return Token lifecycle busy; retry the managed operation after its current owner completes. The retry reloads the winning package and normally reuses it. This response does not mean that the grant expired or that the user must sign in.

./vendor/m7-identity-cli-php-0.1.3/bin/m7-identity ensure \
  --app example-device --profile agents \
  --refresh-mode ack_supersede_pending > /dev/null

./vendor/m7-identity-cli-php-0.1.3/bin/m7-identity token status \
  --app example-device --grant device-code --profile agents

The example assumes a configured and device-authorized native profile. Ensure stores the complete resulting package before returning. Token status contains metadata only; token, bundle and report output contain credentials and must not be logged.

All supported managed writers participate: ensure and authenticated requests, explicit refresh/ACK, machine acquisition, device pickup, import, promotion, discard/reset and app/profile administration. Human approval waits stay unlocked; each device token poll and its conditional storage commit run together. Other profiles remain independent and protected-resource requests run after token coordination releases.

Permanent private lock files live below the store's .locks/ directory, outside deletable profiles. The OS releases held locks when a process exits, including a forced termination. Never unlink a lock file or steal it based on elapsed time.

Delayed results and recovery

A sign-in/import, reset, recreation or configuration change invalidates older acquisition attempts. A late pending response cannot replace a different active generation. ACK promotion requires the exact package that was durably saved. A failed operation cannot resave its old snapshot over a newer result.

A lost ACK response retains the exact pending activation for an idempotent retry. Repeating that checkpoint does not create another generation. Locally obsolete pending packages and equivalent legacy duplicates are retained in protected history before automatic selection; distinct unresolved candidates require inspection and explicit --id selection. Do not choose solely by a filename's timestamp or delete all pending state to hide an uncertain result.

ack_supersede_pending is still the normal fault-tolerant authority mode, not a replacement for client coordination. It can supersede a never-active child when refreshing from the retained active predecessor. ACK confirms that specific child before it is promoted locally.

If an interruption lasts until the acknowledged candidate's access token expires, the authority can reject a repeat ACK even when its refresh credential remains live. That case needs explicit recovery; the CLI never blindly promotes an unconfirmed package or weakens revocation checks. Process-death recovery tests do not establish durability against filesystem or power loss.

An authenticated resource request is not automatically replayed after a failure. Only retry a business mutation when its dispatch status and the resource API's idempotency contract establish that doing so is safe.

Copies and custom storage

App/profile copy requires explicit source and destination and preserves permitted configuration, passwords and access-only material without hard links. CLI/PHP 0.1.3 rejects a source containing refresh or activation bundles, including history. Authorize a separate grant for an independently used profile; use one shared profile for agents that should share a grant.

Explicit imports are deliberate operator replacements. Custom asynchronous CLI store writers must capture the authorization epoch and condition their import on that epoch. Raw file writes, separately copied stores and storage-neutral ensureAccessToken() calls need caller-owned coordination, durable checkpointing and conditional commits. The protocol library does not choose those policies.