agl 1.0.17 → 21.0.2

package/readme.plan.md

@@ -0,0 +1,188 @@
+# AGL Package Transition Plan
+
+## Outcome
+
+Move the published pnpm-global installation from
+`@modelprofile.com/harness-controller@20.0.2` to the bridge
+`@modelprofile.com/harness-controller@20.0.3`, then to the exact unscoped target
+`agl@21.0.0`. The operator runs two separate commands and waits for each to
+finish:
+
+```sh
+hcon upgrade --port 4097
+hcon upgrade --port 4097
+```
+
+The first command remains a same-package `hcon` upgrade. The second is the
+bridge-owned cross-package transition. After both succeed, the management
+command is `agl`.
+
+## Exact Identities
+
+| Role | Package | Version | CLI | Management | Transaction responsibility |
+| --- | --- | --- | --- | --- | --- |
+| Published source | `@modelprofile.com/harness-controller` | `20.0.2` | `hcon` | v1 | Creates format 2 |
+| Bridge | `@modelprofile.com/harness-controller` | `20.0.3` | `hcon` | v1 | Completes format 2 and creates format 3 |
+| Target | `agl` | `21.0.0` | `agl` | v2 | Inherits and completes format 3 |
+
+The repository is `modelprofile.com/agl`. During the bridge release,
+`.smartconfig.json` points Git operations at `agl` while npm publication remains
+`@modelprofile.com/harness-controller` with the existing registries and release
+targets.
+
+## Stable Contracts
+
+- Preserve controller IDs, database and collection names, passkey RP/origin and
+  credential records, SmartSecret service/store/account identities, harness
+  IDs, audit vocabulary, browser storage keys, and persisted protocol fields.
+- Preserve existing `HARNESS_CONTROLLER_*` environment variables, private IPC
+  identities, log locations, and management coordination paths.
+- Preserve user projects, workspaces, controller runtime configuration, session
+  state, Flex credentials, Git captures, and controller-owned worktrees.
+- Keep the current installed data root at `$XDG_CONFIG_HOME/hcon` (default
+  `~/.config/hcon`). Its migration is already committed; neither upgrade phase
+  performs another data-root move or imports the old root again.
+- Development checkouts continue to use `.nogit`. Package and CLI branding may
+  change only at the public target boundary, not inside persisted identities.
+
+## Coordination Compatibility
+
+The coordination envelope remains version 2 across all three artifacts. Owner
+records, start and upgrade admission, worker payloads, launch and action grants,
+transaction mutation guards, and token metadata retain that shared envelope.
+
+Format-2 transactions describe a same-package transition with source version,
+optional target version, and optional `targetStartupInvoked`. The 20.0.2 worker
+creates this format. Bridge 20.0.3 must read and mutate the inherited transaction
+exactly and must not add format-3 package fields to it.
+
+Format-3 transactions are created only by the exact bridge identity. They pin
+both package names, versions, management versions, CLI names, and direct CLI
+paths. The source side remains management v1; the target side is management v2.
+Target startup validates the exact target-only pnpm topology, global root,
+direct CLI path, package/version identity, management version, and inherited
+startup authority before registering itself in the transaction.
+
+## Phase 1: Source To Bridge
+
+1. The active 20.0.2 `hcon` creates a format-2 transaction and detached worker.
+2. The old package's `latest` tag must resolve to exact 20.0.3. Normal semver
+   comparison still refuses a downgrade.
+3. For a running controller, the worker verifies the exact source process,
+   durably prepares the bounded session cohort through management v1, stops the
+   controller, installs 20.0.3, records `targetStartupInvoked`, invokes the exact
+   bridge CLI, then finalizes or reopens the cohort.
+4. For a stopped controller, the worker installs and verifies 20.0.3, records
+   terminal package success without `targetStartupInvoked`, and leaves the
+   controller stopped.
+5. Before target startup, a same-package failure may restore exact 20.0.2 and
+   compensate the prepared cohort. After target startup is invoked, recovery is
+   forward-only because startup may have applied forward migrations.
+
+## Phase 2: Bridge To AGL
+
+The exact 20.0.3 bridge creates a format-3 transaction. Before controller
+preparation, shutdown, or global package mutation, its worker resolves
+`agl@21.0.0` from the configured registry and validates the exact package name,
+version, and sole `agl: ./cli.js` binary. Missing, malformed, or mismatched target
+metadata aborts safely while bridge ownership remains intact.
+
+The package transition then uses these durable checkpoints in order:
+
+1. `packageTransitionStarted` is committed immediately before the prepared
+   grouped add of exact bridge and target packages.
+2. `groupedTargetVerified` follows verification that both exact package roots
+   share one pnpm group and that the `hcon` and `agl` shims point to their
+   respective direct CLIs.
+3. `targetPackageCommitStarted` is the irreversible package boundary, committed
+   immediately before the prepared exact-target add.
+4. `targetPackageCommitted` follows target-only verification: the bridge and
+   `hcon` shim are absent, and exact `agl@21.0.0` owns the `agl` shim.
+5. `targetStartupInvoked` is used only when the controller was running. The
+   target start command is prepared first, the marker is committed immediately
+   before execution, and AGL then proves management v2 identity before session
+   finalization.
+
+Before `targetPackageCommitStarted`, failure and stalled-worker recovery
+normalize to exact bridge-only ownership, restart the bridge when it was
+previously running, and compensate sessions. From that checkpoint onward,
+recovery only normalizes toward exact target-only ownership and never restores
+the bridge. Recovery refuses to adopt an unmarked target process, avoids a
+duplicate start while retained target authority is alive, and preserves the
+transaction for bounded forward recovery after the startup marker.
+
+## Running And Stopped Paths
+
+For both phases, a running controller seals prompt admission, records and
+prepares the exact bounded cohort, verifies that source writers and the source
+port have quiesced, changes packages, starts the authorized target, and finalizes
+once. `--continue-sessions` controls continuation; without it, successful target
+startup only reopens admission. Uncertain pause cleanup remains fail-closed.
+
+A stopped controller has no inherited cohort. Package verification and recovery
+still apply, but no target startup marker is written and no controller is
+started. After phase 1 the next command remains `hcon`; after phase 2 the next
+command is `agl`.
+
+## Git Startup Fixes
+
+- Before SmartData or runtime initialization, validate the committed data root
+  and create its `git-reversion` parent with mode 0700, or validate an existing
+  parent as a same-user, non-symlink directory with no group or world access. Do
+  not create missing data-root ancestors or replace an unsafe existing entry.
+- Keep controller-specific Git roots keyed by the existing controller ID hash;
+  the package rename does not rename or relocate Git state.
+- On pristine projects, and projects containing only exact durable
+  discovery-limit barriers, recover by validating project identity and durable
+  records without traversing the project tree.
+- When a definitively new capture in otherwise pristine or barrier-only state
+  exceeds repository or directory discovery bounds, publish a crash-recoverable
+  empty `git.discovery-limit` non-revertible barrier. Existing repository-bearing
+  or ambiguous state must instead fail closed without mutation or rediscovery.
+- Enforce repository candidate limits during discovery so scanning stops at the
+  first provable overflow rather than traversing later paths.
+
+## Candidate And Publication Sequence
+
+1. Freeze a 20.0.3 bridge candidate under the old npm identity, `hcon` binary,
+   and management v1. Verify its packed artifact and both upgrade formats in an
+   isolated pnpm global home and controlled registry.
+2. Preserve that exact source as the `v20.0.3` commit and tag before making any
+   target identity change.
+3. Publish phase 1 as `@modelprofile.com/harness-controller@20.0.3` to the
+   existing registries and confirm that the old package's `latest` tag resolves
+   exactly to 20.0.3. Verify the first invocation from actual published 20.0.2.
+4. From the bridge tag, prepare and verify the target candidate with package
+   `agl`, version 21.0.0, CLI `agl`, and management v2 while preserving every
+   stable contract and the shared coordination envelope.
+5. Preserve the target as the `v21.0.0` commit and tag, then publish phase 2 as
+   exact unscoped `agl@21.0.0`. Until this publication exists, bridge preflight
+   must fail without stopping the controller or mutating packages.
+6. Run the final public-registry E2E from published 20.0.2 through both explicit
+   `hcon upgrade` invocations and verify that only `agl` remains installed and
+   `agl` is the final command.
+
+Do not deprecate any legacy package version before both publications and the
+final public-registry E2E succeed. After success, deprecation may direct users to
+the two-command bridge path; published bridge artifacts must remain installable
+for recovery.
+
+## Verification
+
+- Build, production type checking, test type checking, focused management and
+  package-transition tests, the full Node/browser suite, and diff sanity checks.
+- Immutable format-2 fixtures proving 20.0.3 consumes and mutates 20.0.2 state
+  without format-3 fields.
+- Format-3 validation for exact identities, checkpoint implication order,
+  management v1 to v2 handoff, direct CLI ownership, and inherited startup.
+- Target-resolution failures proving no controller preparation, shutdown, or
+  package mutation occurs before exact `agl@21.0.0` metadata is accepted.
+- Real pnpm grouped, source-only, and target-only topology tests, including
+  command interruption and recovery at every package checkpoint.
+- Running and stopped paths for both invocations, with session continuation both
+  enabled and disabled, plus worker-loss and retained-target recovery.
+- Git startup tests for secure parent creation, unsafe-parent rejection, pristine
+  no-traversal recovery, bounded discovery barriers, and crash-safe replay.
+- Final E2E from actual published 20.0.2 to bridge 20.0.3 to target 21.0.0,
+  confirming data, credentials, sessions, Git state, command ownership, and the
+  unchanged `~/.config/hcon` root.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: 'agl',
+  version: '21.0.2',
+  description: 'Agent Gateway Layer for OpenCode and FlexHarness sessions'
+}