akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/workflows/{source-ir/semantics.js → source-semantics.js}

@@ -1,12 +1,12 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/** Shared semantic validation for every workflow source-IR producer and decoder. */
+/** Semantic checks shared by the workflow grammars (`parser.ts`, `github-yaml.ts`) and freeze. */
 import fs from "node:fs";
 import path from "node:path";
-import { parseBuiltinCommandAction } from "../../commands/command/builtin-action.js";
-import { parseSchedule } from "../../tasks/schedule.js";
-import { classifyWorkflowSourceUses } from "./uses.js";
+import { parseBuiltinCommandAction } from "../commands/command/builtin-action.js";
+import { classifyTargetRef } from "../execution/target-ref.js";
+import { parseSchedule } from "../tasks/schedule.js";
 export class WorkflowSourceSemanticError extends Error {
     code;
     constructor(code, message) {
@@ -15,6 +15,14 @@ export class WorkflowSourceSemanticError extends Error {
         this.name = "WorkflowSourceSemanticError";
     }
 }
+/** The argv a `run:` string executes under `shell`. */
+export function workflowShellCommand(shell, content) {
+    if (shell === "cmd")
+        return ["cmd", "/d", "/s", "/c", content];
+    if (shell === "pwsh" || shell === "powershell")
+        return [shell, "-Command", content];
+    return [shell, "-c", content];
+}
 export function canonicalizeWorkflowCron(value) {
     const canonical = value.trim().split(/\s+/).join(" ");
     if (canonical.startsWith("@") || canonical.split(" ").length !== 5) {
@@ -66,28 +74,21 @@ function hasControlCharacter(value) {
     }
     return false;
 }
-export function classifyWorkflowStepUses(value, classifier = classifyWorkflowSourceUses) {
+export function classifyWorkflowStepUses(value) {
     if (value.includes("${{")) {
         throw new WorkflowSourceSemanticError("unsupported-github-expression", "GitHub expressions are unsupported in uses.");
     }
     if (value.length === 0 || value.trim() !== value || /\s/.test(value)) {
         throw new WorkflowSourceSemanticError("unsupported-uses-target", "uses must be one exact, non-empty executable ref");
     }
-    let target;
+    if (value === "akm/command")
+        return { kind: "builtin-command", ref: "akm/command" };
     try {
-        target = classifier(value);
+        return classifyTargetRef(value);
     }
     catch (cause) {
         throw usesFailure(value, cause);
     }
-    // P3a (docs/plans/specs/p3a-plan-v5-child-freeze.md §1.3(2)/§4, A-N4): a
-    // `kind: "workflow"` target used to throw `nested-workflow-unsupported`
-    // here. That rejection is REMOVED — classification returns the workflow
-    // target like any other target-ref-shaped `uses:`, and freeze decides
-    // (`src/workflows/freeze/targets/child-workflow.ts`, the ONE recursive
-    // child-workflow resolver both the direct and task-wrapped composition
-    // forms route through).
-    return target;
 }
 /**
  * Validate AKM's built-in command action at the shared source/decoder boundary.
@@ -121,11 +122,6 @@ export function validateWorkflowBuiltinCommand(value, mode) {
     }
     return action;
 }
-export function rejectNulInArgv(command) {
-    if (command.some((argument) => argument.includes("\0"))) {
-        throw new WorkflowSourceSemanticError("invalid-exec-argv", "Direct exec argv may not contain NUL bytes.");
-    }
-}
 function usesFailure(value, cause) {
     const message = cause instanceof Error ? cause.message : String(cause);
     const code = value.startsWith("docker://")

package/dist/workflows/validate-summary.js

@@ -18,13 +18,8 @@
 import validateSummaryJudgePrompt from "../assets/prompts/validate-summary-judge.md" with { type: "text" };
 import { parseJsonResponse } from "../core/parse.js";
 /**
- * Parse the judge's raw response into a well-formed verdict, or `undefined`
- * when the response is malformed (unparseable, or missing a boolean
- * `complete`). This is the ONE verdict parser: {@link validateStepSummary}
- * fails closed through it, and the engine's gate wrapper (step-work.ts) uses
- * the same function to classify a malformed verdict as verifier
- * INFRASTRUCTURE failure — never an honest rejection that would consume a
- * gate loop — so the two classifications cannot drift.
+ * The one verdict parser: a well-formed verdict, or `undefined` when malformed
+ * (which the engine treats as a verifier failure, never a rejection).
  */
 export function parseJudgeVerdict(raw) {
     const parsed = parseJsonResponse(raw);

package/docs/integration/bundling-akm.md

@@ -29,49 +29,57 @@ akm migrate apply
 
 In order, every run applies (or, under `status`/`--dry-run`, plans):
 
-1. **Legacy config lift** — `extraParams` keys on an engine config moved onto
-   first-class fields.
-2. **Pending `state.db` migrations**, historical-destructive ones included.
-   This is the only path (besides `akm upgrade`, which calls the same code)
-   that is allowed to apply a destructive migration to an existing,
-   unversioned or behind-generation `state.db` — see
+1. **config.json in its current shape** (`configFile`): retired and unknown
+   keys dropped, legacy `extraParams` lifted onto first-class fields, the
+   legacy `stashDir`/`sources[]`/`installed` layout converted to
+   `bundles`/`defaultBundle`. Config loading already does all of this in
+   memory; this persists it under a backup.
+2. **Pending `state.db` migrations**, historical-destructive ones included
+   (`stateMigrations`). This is the only path (besides `akm upgrade`, which
+   calls the same code) that is allowed to apply a destructive migration to an
+   existing, unversioned or behind-generation `state.db` — see
    [One-way state.db](#one-way-note-statedb-migrations-are-one-way) below.
-3. **Task sources**: task-v2 files to task v3, then task-v3 files to task
-   source v4. Each generation keeps its own lock and backup, so a file
-   blocked in one generation does not stop the other from converting files
-   that are already current.
-4. **Stash residue sweeps**: superseded pre-0.9.0 `.akm` files and stale
-   filesystem transactions, scoped to the configured bundle (skipped
-   entirely when no bundle is configured yet).
+3. **Task files**: every task file at version 2 or 3, and every version 4
+   file still carrying the retired `schedule[].enabled` key, rewritten as
+   task source v4 (`taskFiles`) under one backup directory per run. A file
+   the planner cannot convert unambiguously is reported `blocked` and left
+   alone; the rest still convert.
+4. **Residue sweep**: superseded pre-0.9.0 `.akm` files in the stash and the
+   transaction-journal, maintenance-barrier, lock-mutex and version-stamp
+   files older releases kept under `$DATA`/`$STATE`/`$CONFIG` (`deadResidue`).
+
+The step list in [`docs/reference/cli.md`](../reference/cli.md#migrate) is the
+authoritative one; the two must agree.
 
 ### The plan JSON
 
-One JSON object on stdout, always. A current install, nothing to do:
+One JSON object on stdout, always, with one field per step. A current
+install, nothing to do, as `akm migrate status` prints it (under `apply` the
+per-step objects carry results instead — `applied`, `removed` — with the
+same step names):
 
 ```json
 {
   "schemaVersion": 1,
   "status": "current",
   "blockers": [],
-  "configExtraParams": { "applied": false, "lifted": [], "conflicts": [] },
+  "configFile": { "keys": [], "changed": false, "applied": false },
   "stateMigrations": { "pending": [] },
-  "taskV3Migration": { "schemaVersion": 1, "generation": "task-v2-to-v3", "changed": 0, "skipped": 4, "blocked": 0, "files": [] },
-  "taskV4Migration": { "schemaVersion": 1, "generation": "task-v3-to-v4", "changed": 0, "skipped": 4, "blocked": 0, "files": [] }
+  "taskFiles": { "schemaVersion": 1, "changed": 0, "skipped": 0, "blocked": 0, "files": [] },
+  "deadResidue": { "pending": [] }
 }
 ```
 
-`akm migrate status` against a tree with one blocked task file (`taskV3Migration`
-omitted below for brevity — its shape is identical):
+`akm migrate status` against a tree with one blocked task file:
 
 ```json
 {
   "schemaVersion": 1,
   "status": "blocked",
-  "blockers": ["with-on-non-command-target"],
+  "blockers": ["tasks/nightly.yml: with-on-non-command-target"],
   "stateMigrations": { "pending": [] },
-  "taskV4Migration": {
+  "taskFiles": {
     "schemaVersion": 1,
-    "generation": "task-v3-to-v4",
     "changed": 3,
     "skipped": 1,
     "blocked": 1,
@@ -109,16 +117,14 @@ Key fields:
 | Field | Meaning |
 | --- | --- |
 | `stateMigrations` | `{ pending: string[] }` under `status`/`--dry-run`; `{ applied: string[], safetyCopyPath?: string }` after a real `apply`. `safetyCopyPath` is present only when a historical-destructive migration ran — see below. |
-| `taskV3Migration` / `taskV4Migration` | Per-generation summary: `changed`/`skipped`/`blocked` counts and a `files[]` array with each file's `status` and `reason`. |
-| `backupPath` / `taskV4BackupPath` | Present after a real apply that changed at least one file in that generation — a timestamped snapshot directory. |
-| `deadResidue` / `staleTxns` | Present only when a bundle is configured. `{ pending: [...] }` under a read-only run, `{ removed: [...] }` / `{ recovered: [...] }` after apply. |
+| `taskFiles` | `changed`/`skipped`/`blocked` counts and a `files[]` array with each file's `status` and `reason`. |
+| `backupPath` / `applied` | Present after a real apply that rewrote at least one task file: the run's backup directory and how many files it rewrote. |
+| `deadResidue` | `{ pending: [...] }` under a read-only run, `{ removed: [...] }` / `{ recovered: [...], quarantined: [...], deferred: [...] }` after apply. An untrusted journal (unreadable `journal.json`, or a fence violation) is quarantined to `$DATA/txn-quarantine`; a trusted, fenced journal whose `rollback`/`finalize` throws is deferred, left in place under `$DATA/txn/<rootNs>/`. Neither is thrown, and neither sets `status` to `blocked`. `staleTxns.pending` entries carry `wouldQuarantine: { reason }` when the journal's read-only fence check alone (not a `rollback`/`finalize` run) already shows it would be quarantined by a real apply. |
 
 **Backups and their retention:**
 
-- Task-source backups (task-v2→v3 and v3→v4) go to
-  `<dataDir>/backups/task-v3/<timestamp>-<uuid>/` and
-  `<dataDir>/backups/task-v4/<timestamp>-<uuid>/` respectively — one
-  directory per apply run, pruned to the **5 most recent** automatically.
+- Task-file backups go to `<dataDir>/backups/tasks/<timestamp>-<uuid>/`,
+  one directory per apply run that rewrote a file; nothing prunes them.
 - Config backups go to `<cacheDir>/config-backups/config-<ISO-ts>.json`,
   also capped at **5**.
 - A `state.db` historical-destructive migration writes a verified sibling
@@ -197,25 +203,26 @@ that wording is not a stable interface.
 (`status: "fail"`).
 
 The check that replaces grepping akm's refusal text is a **hard check**
-named `state-db-migrations`:
+named `state-db-migrations`. Every `state.db` open applies pending migrations
+(copying the file to `state.db.pre-<id>.bak` first when one drops schema), so
+after an upgrade the check passes and names what health's own open applied:
 
 ```json
 {
   "name": "state-db-migrations",
-  "status": "fail",
-  "message": "1 pending state.db migration(s) (018-drop-dead-lane-schema); run `akm migrate apply`.",
-  "evidence": { "path": "/data/akm/state.db", "pending": ["018-drop-dead-lane-schema"] }
+  "status": "pass",
+  "message": "Applied 11 pending state.db migration(s) on open (018-drop-dead-lane-schema … 028-improve-ledger); the pre-migration copy is /data/akm/state.db.pre-018-drop-dead-lane-schema.bak.",
+  "evidence": {
+    "path": "/data/akm/state.db",
+    "pending": [],
+    "applied": ["018-drop-dead-lane-schema", "…", "028-improve-ledger"],
+    "backupPath": "/data/akm/state.db.pre-018-drop-dead-lane-schema.bak"
+  }
 }
 ```
 
-It reads `evidence.pending` — a read-only preflight, never the managed open
-— so `akm health` can report this state even though **an ordinary command
-that opens `state.db` refuses to touch a pending historical-destructive
-migration by design**, naming `akm upgrade` and `akm migrate apply` as the
-only two commands allowed to apply one. Before this check existed, that
-refusal surfaced as a crash (config-error exit) instead of a normal `fail`
-row — this is what a bundler should now watch for `state-db-migrations` to
-report, instead of grepping error text for a fixed remedy string.
+It is `fail` only when a pending migration could not be applied; `evidence.pending`
+then names what is still pending. Watch this row's `status`, not error text.
 
 ## The `akm-migrate` executable
 
@@ -259,7 +266,7 @@ rather than rely on `$HOME`-derived defaults (names verified against
 | `AKM_CONFIG_DIR` | `config.json`'s directory. |
 | `AKM_DATA_DIR` | Durable, non-regenerable data: **`index.db` and `state.db` live here.** This is the directory a migration snapshot's safety copy sits beside. |
 | `AKM_CACHE_DIR` | Regenerable cache: registry downloads, config backups, task logs. Safe to discard between image builds (not between boots of the same running install). |
-| `AKM_STATE_DIR` | **Not** where `state.db` lives, despite the name — this is the XDG "state" directory. Holds scheduled-task invocation context, companion-plugin hook state (Claude Code / OpenCode hook logs), and, per stash, `akm improve`'s machine-local writers (`improve/distill-rejected/`, `improve/eval-cases/`, `improve/measurement/verdicts/`) and whole-run lock (`locks/`) — see [Storage locations](https://github.com/itlackey/akm/blob/main/docs/architecture/internals/storage-locations.md). Set it anyway if you schedule akm tasks inside the image, so that context is captured consistently rather than falling back to `$HOME/.local/state/akm`. |
+| `AKM_STATE_DIR` | **Not** where `state.db` lives, despite the name — this is the XDG "state" directory. Holds scheduled-task invocation context, companion-plugin hook state (Claude Code / OpenCode hook logs), and, per stash, `akm improve`'s machine-local writers (`improve/measurement/verdicts/`) and whole-run lock (`locks/`) — see [Storage locations](https://github.com/itlackey/akm/blob/main/docs/architecture/internals/storage-locations.md). Set it anyway if you schedule akm tasks inside the image, so that context is captured consistently rather than falling back to `$HOME/.local/state/akm`. |
 
 Set all five to paths that persist across container restarts (a mounted
 volume), or `akm migrate apply` will see an empty `state.db` on every boot

package/docs/migration/README.md

@@ -5,6 +5,7 @@ Upgrade guides and per-release migration notes.
 - [v0.9.1 -> v0.9.2 migration guide](v0.9.1-to-v0.9.2.md) -- Task-v2/task-v3 to task source v4 conversion, the durable-v4-family workflow boundary at executable `irVersion: 5`, and release behavior changes
 - [v0.9.2 release note](release-notes/0.9.2.md) -- Self-contained terminal upgrade summary shipped for `akm help migrate 0.9.2`
 - [v0.9.16 release note](release-notes/0.9.16.md) -- Source-bound scheduler grants, local execution authority, and split unsafe overrides
+- [v0.9.17 release note](release-notes/0.9.17.md) -- Tolerant readers, one config migration step, a plain scheduler list, less machinery, and the upgrade rehearsal gate
 - [v0.8 -> current v0.9 migration guide](v0.8-to-v0.9.md) -- Package upgrade with fresh current config/state and explicit task conversion
 - [v0.7 -> v0.8 migration guide](v0.7-to-v0.8.md) -- Task schema and 0.8-era changes
 - [v0.5 -> v0.6 migration guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) -- Terminology cut, registry schema v3, publisher changes

package/docs/migration/release-notes/0.9.17.md

@@ -0,0 +1,43 @@
+Migration notes for akm v0.9.17
+
+Upgrading no longer needs a manual step to keep working, and there is less
+machinery to break.
+
+Readers tolerate what older releases wrote, except task sources. A
+`version: 2` or `version: 3` task source fails on its own with
+`TASK_SCHEMA_VERSION_UNSUPPORTED`, naming `akm migrate apply`, which converts
+it to `version: 4` once; the other tasks keep running. A config key this
+release does not know -- retired, misspelled, or written by a newer release --
+is kept in memory and named once, never a reason to refuse the config;
+ordinary writes round-trip it, and `akm migrate apply` drops it.
+`akm migrate apply` has one config step (`configFile`): read config.json
+through the same pipeline every load runs and write the current shape back,
+under a backup.
+
+Scheduling is one list. `scheduler.enabled` in config.json holds the
+fully-qualified refs this host schedules (`bundle//tasks/x`). The
+0.9.17-alpha `{kind, ref, sourceId}` grant objects are read as their ref. A
+config with no list at all -- every release before 0.9.17 -- means "keep
+what is installed": the first `akm task sync` (or `setup`, `task enable`,
+`task disable`, `task add`) after the upgrade takes the akm-written rows
+already in the native scheduler as the host's choice, writes the list, and
+says so. An explicit list, empty or not, is never second-guessed. There are
+no grants, no source identities, no carry-forward and no fire-time gate.
+
+Removed machinery: filesystem transaction journals for proposal accept/revert
+(the asset is written, then the proposal row and its event are recorded in
+one state.db transaction; a crash in between leaves a re-acceptable pending
+proposal); the maintenance barrier, its per-process activity registry (the
+source of the lock-sidecar leak) and the SQLite lock-operation mutex (a lock
+file is one `O_EXCL` create); startup version reconciliation and
+`--host-local`; the akm-install enumerator and `akm upgrade --version/--tag`;
+the upgrade and transaction health advisories; the `akm info` compat
+manifest. `akm migrate apply` removes the files those left under `$DATA`,
+`$STATE` and `$CONFIG`.
+
+Every historical shape akm has written is exercised by the upgrade rehearsal
+(`tests/integration/upgrade-rehearsal/`) before each release: a real previous
+release builds a home, the candidate installs over it in place, and the
+rehearsal drives migrate, bundle list, search, show, task sync, health and a
+scheduled task's generated cron command, then confirms the previous release
+still runs against the candidate-written home.

package/docs/migration/v0.9.1-to-v0.9.2.md

@@ -53,14 +53,30 @@ migration contract.
    below.
 
 Everything else below can happen after the binary upgrade, at your own
-pace: task sources keep failing closed with an actionable hint until you
-migrate them (nothing silently breaks or half-runs), and pre-`irVersion`-5
-runs stay inspectable indefinitely.
+pace: an unmigrated v2/v3 task source keeps reading and running through the
+in-memory read shim, with a one-line deprecation warning, until you migrate
+it (nothing silently breaks or half-runs, and only a genuinely unmigratable
+shape fails closed with an actionable hint), and pre-`irVersion`-5 runs stay
+inspectable indefinitely. (0.9.17-alpha.7 removed that shim: a v2/v3 task
+source now fails on its own, naming `akm migrate apply`, which `akm upgrade`
+runs after an install.)
 
 ## Task sources
 
-akm 0.9.2 has shipped three task source generations. Only the newest,
-**task source v4**, is accepted by `src/` in this release.
+akm 0.9.2 has shipped three task source generations. **Task source v4** is
+the current, standing grammar; an older `version: 2` or `version: 3` file
+still reads and runs through an in-memory read shim that converts it to v4
+on the same bytes `akm migrate apply` would produce, with a one-line stderr
+deprecation warning and no disk write. Only a v2/v3 document the
+deterministic conversion itself cannot resolve fails to load. `akm migrate
+apply` remains the way to rewrite the file on disk and silence the warning.
+(A later release — see the [Tasks reference](../reference/tasks.md) for the
+current grammar — extended the same kind of shim to a `version: 4` document
+whose `schedule[]` still carries a per-entry `enabled` key, retired from
+task source v4's own grammar since; the field is stripped without being
+read, never re-added. 0.9.17-alpha.7 removed both shims: akm now reads only
+task source v4, and each older file fails on its own, naming
+`akm migrate apply`.)
 
 **Before — 0.9.1 task v2:**
 
@@ -77,7 +93,7 @@ redact: [REVIEW_TOKEN]
 ```
 
 **An intermediate generation — task v3** (shipped earlier in the 0.9.x
-line; also no longer accepted):
+line; also read only through the shim now, not as a standing grammar):
 
 ```yaml
 version: 3
@@ -667,7 +683,7 @@ phase-specific code:
 | Code | Domain |
 |---|---|
 | `TASK_SOURCE_INVALID` | A task document's field- or semantic-level validation failure, or a malformed/oversized/too-deep YAML front end failure. |
-| `TASK_SCHEMA_VERSION_UNSUPPORTED` | A task document's `version:` is not `4` and is recognizable as a legacy generation (`3` or `2`). |
+| `TASK_SCHEMA_VERSION_UNSUPPORTED` | A task document's `version:` is `3` or `2` and the in-memory read shim's deterministic conversion cannot resolve it — a human decision is needed (see [Task sources](#task-sources)); a convertible v2/v3 document reads through the shim instead of failing. From 0.9.17-alpha.7, every v2/v3 document fails this way, naming `akm migrate apply`. |
 | `TARGET_REF_INVALID` | A value is not a canonical `commands/`, `scripts/`, `tasks/`, or `workflows/` asset ref (malformed shapes, GitHub locators, other asset families). |
 | `WORKFLOW_SOURCE_INVALID` | A workflow-source compile failure other than the one below. |
 | `COMPOSITION_INVALID` | A composition-policy rejection: a rejected `with:`, a multi-job document, a composition cycle/depth/size violation. |