akm-cli 0.9.0 → 0.9.1-beta.2

package/dist/storage/repositories/index-connection.js

@@ -10,11 +10,13 @@
  * import their opener from a sibling here instead of reaching up into the
  * indexer — inverting the old storage→indexer arrow.
  */
-import fs from "node:fs";
 import { createRequire } from "node:module";
+import { ConfigError } from "../../core/errors.js";
+import { classifyPathAccess, describeInaccessiblePath } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
 import { openDatabase } from "../database.js";
 import { openManagedDatabase } from "../managed-db.js";
+import { SQLITE_BUSY_TIMEOUT_MS } from "../sqlite-pragmas.js";
 import { ensureSchema } from "./index-schema.js";
 import { loadVecExtension, warnIfVecMissing } from "./index-vec-repository.js";
 export function openIndexDatabase(dbPath, options) {
@@ -71,20 +73,53 @@ export function openExistingDatabase(dbPath) {
     // tests/storage/open-existing-database-no-create.test.ts. `create: false`
     // below is the race-free backstop for this pre-check.
     const resolvedPath = dbPath ?? getDbPath();
-    if (!fs.existsSync(resolvedPath)) {
+    assertIndexPathReadable(resolvedPath);
+    if (classifyPathAccess(resolvedPath).access === "absent") {
         throw new Error(`Index database not found at ${resolvedPath}. Run 'akm index' to build it.`);
     }
     return openManagedDatabase({ path: resolvedPath, init: loadVecExtension, create: false });
 }
+/**
+ * Refuse to treat an UNREADABLE index as a missing one (#791).
+ *
+ * `fs.existsSync()` — which every one of these gates used to call — returns
+ * `false` for `EACCES` exactly as for `ENOENT`, so an index this process cannot
+ * read looked identical to one that had never been built. Callers then took
+ * their "no index yet" branch: `search`/`curate` returned no hits at exit 0 and
+ * told the user to run `akm index`, which would not have helped and which they
+ * may not have permission to do either.
+ *
+ * A `ConfigError` here exits 78 through the standard `{ok:false, error, code}`
+ * envelope, so both a human and a machine caller can tell "nothing indexed"
+ * from "I cannot see the index".
+ */
+export function assertIndexPathReadable(resolvedPath) {
+    const { access, code } = classifyPathAccess(resolvedPath);
+    if (access !== "inaccessible")
+        return;
+    throw new ConfigError(`Index database exists but is not readable: ${describeInaccessiblePath(resolvedPath, code)}.`, "DATA_DIR_UNREADABLE");
+}
 /**
  * Open an existing index for queries without creating directories, a database
  * file, journals, or running write-capable pragmas/schema initialization.
  */
 export function openReadonlyExistingDatabase(dbPath) {
     const resolvedPath = dbPath ?? getDbPath();
-    if (!fs.existsSync(resolvedPath))
+    // `undefined` means "no index" — reserve it for a genuinely absent one, and
+    // let an unreadable index raise instead of masquerading as absent (#791).
+    assertIndexPathReadable(resolvedPath);
+    if (classifyPathAccess(resolvedPath).access === "absent")
         return undefined;
-    return openDatabase(resolvedPath, { readonly: true, create: false });
+    const db = openDatabase(resolvedPath, { readonly: true, create: false });
+    // This opener bypasses openManagedDatabase/applyStandardPragmas by design (no
+    // journal or schema work on a read-only handle), but that also left
+    // busy_timeout at SQLite's default of 0. In WAL that is harmless — readers
+    // never block — but in the DELETE/TRUNCATE modes the network-FS fallback and
+    // AKM_SQLITE_JOURNAL_MODE can select, a concurrent writer makes every read
+    // fail instantly with SQLITE_BUSY. busy_timeout is legal on a read-only
+    // connection, so apply just that one.
+    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+    return db;
 }
 export function closeDatabase(db) {
     db.close();

package/dist/storage/repositories/index-entries-repository.js

@@ -13,6 +13,7 @@ import path from "node:path";
 import { parseBundleRef } from "../../core/asset/asset-ref.js";
 import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
 import { bestEffort } from "../../core/best-effort.js";
+import { isPathAbsent } from "../../core/path-access.js";
 import { getStateDbPath, withStateDb } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
 import { buildSearchText } from "../../indexer/search/search-fields.js";
@@ -278,7 +279,11 @@ export function rekeyEntryInPlace(db, opts) {
  * history (live-asset-wins). Best-effort + guarded on state.db's existence.
  */
 function rewriteUsageEventRefForMove(opts) {
-    if (!fs.existsSync(getStateDbPath()))
+    // Every other failure in here throws (see the catch below) precisely because
+    // a move that quietly drops its usage history is a wrong answer wearing a
+    // success. An unreadable state.db must not be the one silent exception —
+    // only a state.db that was never created skips (#791).
+    if (isPathAbsent(getStateDbPath()))
         return;
     // `usage_events.entry_ref` is the fully-qualified item_ref
     // (`<bundle>//<conceptId>`).

package/dist/storage/repositories/index-meta-repository.js

@@ -17,6 +17,17 @@ export function getMeta(db, key) {
 export function setMeta(db, key, value) {
     db.prepare("INSERT OR REPLACE INTO index_meta (key, value) VALUES (?, ?)").run(key, value);
 }
+/**
+ * Remove a meta key entirely.
+ *
+ * Distinct from writing an empty string: absence is what callers test for
+ * (`getMeta(...) === undefined`), and it is what lets a value be re-derived —
+ * clearing `embeddingDim` after a model change is how the vec table gets
+ * rebuilt at the new width.
+ */
+export function deleteMeta(db, key) {
+    db.prepare("DELETE FROM index_meta WHERE key = ?").run(key);
+}
 // ── Per-directory index state ───────────────────────────────────────────────
 export function getIndexDirState(db, dirPath) {
     const row = db

package/dist/storage/repositories/index-schema.js

@@ -533,8 +533,23 @@ function ensureBundleRefColumns(db) {
  * fallback.
  */
 function ensureUniqueItemRefIndex(db) {
-    db.exec("DROP INDEX IF EXISTS idx_entries_item_ref");
-    db.exec("CREATE UNIQUE INDEX idx_entries_item_ref ON entries(item_ref)");
+    // Probe before mutating. This ran unconditionally on EVERY open as two
+    // separate autocommit statements, so there was always a window in which the
+    // index did not exist — a concurrent open (registry-cache search, indexer,
+    // improve) could DROP between the other's DROP and CREATE and then fail with
+    // "index idx_entries_item_ref already exists", or serve a query with no index
+    // at all. A DB whose index is already UNIQUE needs no work.
+    const existing = db
+        .prepare("SELECT sql FROM sqlite_master WHERE type = 'index' AND name = 'idx_entries_item_ref'")
+        .get();
+    if (existing?.sql && /\bUNIQUE\b/i.test(existing.sql))
+        return;
+    // Pre-v19 (non-unique index) or absent: convert atomically so a racing open
+    // sees either the old index or the new one, never neither.
+    db.transaction(() => {
+        db.exec("DROP INDEX IF EXISTS idx_entries_item_ref");
+        db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_entries_item_ref ON entries(item_ref)");
+    })();
 }
 /**
  * Returns true when a table exists in the current database.

package/dist/storage/repositories/index-vec-repository.js

@@ -22,10 +22,10 @@ export function loadVecExtension(db) {
     try {
         const esmRequire = createRequire(import.meta.url);
         const sqliteVec = esmRequire("sqlite-vec");
-        // `db` here is the genuine underlying driver handle returned by the storage
-        // boundary (bun:sqlite on Bun, better-sqlite3 on Node) — only structurally
-        // narrowed for callers. sqlite-vec's `load()` accepts either real handle,
-        // so no raw-handle escape hatch is required.
+        // `db` is the storage boundary's handle. On Bun that IS the bun:sqlite
+        // handle; on Node it is a wrapper, which must forward `loadExtension` for
+        // this call to work at all (see openNodeDatabase in storage/database.ts —
+        // it did not, so vec could never load on the entire npm distribution).
         sqliteVec.load(db);
         vecStatus.set(db, true);
     }
@@ -56,7 +56,45 @@ export function setVecFastPathReady(db, ready) {
  * rather than silently returning partial fast-path results.
  */
 export function isVecFastPathReady(db) {
-    return getMeta(db, VEC_FAST_PATH_READY_META) !== "0";
+    if (getMeta(db, VEC_FAST_PATH_READY_META) === "0")
+        return false;
+    // The meta flag alone is not sufficient. An index built while sqlite-vec was
+    // unavailable wrote only BLOB rows, and because "unavailable" outcomes were
+    // not counted as failures the flag was still set to "1" against a table that
+    // is empty or absent. If sqlite-vec later becomes loadable — the user installs
+    // it, or the same index is opened under the other runtime — the fast path
+    // would then be trusted and return zero neighbours while the BLOB table holds
+    // every embedding. Indexes written by earlier versions still carry that stale
+    // flag, so the read path has to verify the table really exists.
+    return hasVecTable(db);
+}
+const vecTablePresent = new WeakMap();
+/**
+ * Whether `entries_vec` exists on this connection, memoized per handle.
+ *
+ * openExistingDatabase loads the vec extension but deliberately does not run
+ * ensureSchema, so the table is not created on read paths — its absence is a
+ * normal state, not an error.
+ */
+function hasVecTable(db) {
+    // Only a POSITIVE result is memoized. The table cannot vanish from a live
+    // connection, but it CAN appear — ensureSchema creates it partway through an
+    // index run — so caching "absent" would pin a stale answer for the rest of
+    // the handle's life.
+    if (vecTablePresent.get(db) === true)
+        return true;
+    let present = false;
+    try {
+        present =
+            db.prepare("SELECT 1 FROM sqlite_master WHERE type IN ('table','view') AND name = 'entries_vec'").get() !==
+                undefined;
+    }
+    catch {
+        present = false;
+    }
+    if (present)
+        vecTablePresent.set(db, true);
+    return present;
 }
 /** Remove both vector representations for an entry whose embedding input changed. */
 export function deleteEntryVectors(db, id) {

package/dist/storage/repositories/workflow-runs-repository.js

@@ -2,6 +2,7 @@
 // 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/.
 import { openStateDatabase, withImmediateTransaction } from "../../core/state-db.js";
+import { borrowScopedStateDb, withStateDbScope } from "../../core/state-db-scope.js";
 import { resolveStorageLocations } from "../locations.js";
 /**
  * Repository owning every raw SQL statement against `workflow_runs` and
@@ -214,8 +215,10 @@ export class WorkflowRunsRepository {
     //
     // Writes to `workflow_run_units` should go through the serialized writer
     // queue (`src/workflows/exec/unit-writer.ts`) when N units may complete
-    // concurrently — SQLite has a single writer and `withWorkflowRunsRepo`
-    // opens a fresh connection per call.
+    // concurrently — SQLite has a single writer per database FILE, and outside a
+    // {@link withWorkflowRunsConnection} scope `withWorkflowRunsRepo` opens a
+    // fresh connection per call (so N concurrent writers would contend against
+    // each other for the write lock).
     getUnitsForRun(runId) {
         return this.db
             .prepare("SELECT * FROM workflow_run_units WHERE run_id = ? ORDER BY started_at ASC, unit_id ASC")
@@ -323,22 +326,55 @@ export class WorkflowRunsRepository {
                 `recoverable state.`);
         }
     }
+    /**
+     * Finish a unit row ONLY while it is still the exact row a specific dispatch
+     * inserted: `running`, with that dispatch's `started_at`. The native
+     * executor's guarded finish (single-driver invariant): a run stolen by
+     * another engine re-dispatches the unit through {@link insertUnit}, which
+     * REPLACES the row (fresh `started_at`, bumped `attempts`) — the stale
+     * driver's finish then matches NOTHING instead of clobbering the new
+     * driver's live dispatch. Returns whether the row was finished; a zero-row
+     * match is a caller-classified outcome here (the executor distinguishes
+     * "replaced by another driver" from "row vanished"), unlike
+     * {@link finishUnit}'s loud throw, whose callers guarantee their row exists.
+     */
+    finishUnitFromDispatch(input) {
+        const result = this.db
+            .prepare(`UPDATE workflow_run_units
+           SET status = ?, result_json = ?, tokens = ?, failure_reason = ?, session_id = ?, finished_at = ?
+           WHERE run_id = ? AND unit_id = ? AND status = 'running' AND started_at = ?`)
+            .run(input.status, input.resultJson, input.tokens, input.failureReason, input.sessionId ?? null, input.finishedAt, input.runId, input.unitId, input.dispatchStartedAt);
+        return Number(result.changes) === 1;
+    }
 }
 /**
- * Open state.db (bound to {@link StorageLocations.stateDb}, the post-cutover
- * home of the `workflow_runs` / `workflow_run_steps` / `workflow_run_units`
- * tables), run `fn` against a {@link WorkflowRunsRepository}, and close the
- * connection exactly once when `fn` settles.
+ * Run `fn` against a {@link WorkflowRunsRepository} bound to state.db
+ * ({@link StorageLocations.stateDb}, the post-cutover home of the
+ * `workflow_runs` / `workflow_run_steps` / `workflow_run_units` tables).
  *
- * Fresh-connection-per-call, mirroring the former workflow.db loan pattern:
- * `openStateDatabase` acquires its own maintenance activity + asserts the
- * current ledger, and the repository owns all table-scoped SQL, so the merge
- * into state.db is a zero-SQL-rewrite repoint. Repository read methods fully
- * materialise their results, so closing here never truncates lazy iteration
- * (WS5 connection-lifetime rule).
+ * Connection lifetime — BORROW-OR-OWN (mirrors `withStateDb`'s `borrowed`
+ * option and `appendEvent`'s `ctx.db` seam):
+ *
+ *   - Inside a {@link withWorkflowRunsConnection} scope, the ambient handle is
+ *     BORROWED and left open for the rest of the scope. A wide `map` fan-out
+ *     therefore opens ONE connection for the whole step instead of two per unit
+ *     (insert + finish) — `openStateDatabase` registers a maintenance activity
+ *     lockfile and opens a read-only ledger-preflight handle on every call, so
+ *     the per-call cost is milliseconds, not microseconds.
+ *   - Outside a scope the behaviour is unchanged: open a fresh connection, run
+ *     `fn`, close it in a `finally`.
+ *
+ * Repository read methods fully materialise their results, so closing an owned
+ * handle here never truncates lazy iteration (WS5 connection-lifetime rule).
+ * The signature and semantics are identical in both modes — reuse is purely an
+ * internal optimisation and no caller needs to know which mode it is in.
  */
 export async function withWorkflowRunsRepo(fn) {
-    const db = openStateDatabase(resolveStorageLocations().stateDb);
+    const stateDb = resolveStorageLocations().stateDb;
+    const borrowed = borrowScopedStateDb(stateDb);
+    if (borrowed)
+        return await Promise.resolve(fn(new WorkflowRunsRepository(borrowed)));
+    const db = openStateDatabase(stateDb);
     try {
         return await Promise.resolve(fn(new WorkflowRunsRepository(db)));
     }
@@ -346,3 +382,20 @@ export async function withWorkflowRunsRepo(fn) {
         db.close();
     }
 }
+/**
+ * Run `fn` with ONE state.db connection shared by every `withWorkflowRunsRepo`
+ * call (and every {@link import("../../core/events.js").appendEvent}) inside its
+ * async extent. The handle opens on first use and closes when `fn` settles;
+ * nesting joins the outer scope.
+ *
+ * Correctness under concurrency: `bun:sqlite` statements and
+ * `withImmediateTransaction` bodies run synchronously to completion, so
+ * logically concurrent units cannot interleave statements on the shared handle
+ * in a single-threaded event loop — sharing REMOVES in-process writer
+ * contention instead of creating it. Cross-process arbitration (WAL,
+ * `busy_timeout`, the run lease) is untouched. See `core/state-db-scope.ts` for
+ * the escaped-async-work guard.
+ */
+export function withWorkflowRunsConnection(fn) {
+    return withStateDbScope(fn, { path: resolveStorageLocations().stateDb });
+}

package/dist/storage/sqlite-pragmas.js

@@ -95,6 +95,17 @@ export function isNetworkFilesystem(fsType) {
         return false;
     return NETWORK_FS_MAGICS.has(fsType);
 }
+/** Options for {@link applyStandardPragmas}. */
+/**
+ * How long a statement waits for a lock before failing with SQLITE_BUSY.
+ *
+ * Exported so read-only openers can apply it too. They cannot run the rest of
+ * the standard set (journal_mode and foreign_keys are write operations), but
+ * the default of 0 makes reads fail INSTANTLY under writer contention — which
+ * matters in the DELETE/TRUNCATE journal modes 0.9.1's network-filesystem
+ * fallback and `AKM_SQLITE_JOURNAL_MODE` can select, where readers do block.
+ */
+export const SQLITE_BUSY_TIMEOUT_MS = 30_000;
 /**
  * Apply AKM's standard opening PRAGMAs to `db`, in order:
  *   1. `journal_mode` = the configured mode (with WAL→DELETE network-FS fallback)
@@ -128,7 +139,7 @@ export function applyStandardPragmas(db, opts = {}) {
     // lock instead of failing immediately with SQLITE_BUSY. For the WAL default
     // this is a no-op (WAL→WAL changes nothing), so byte-identical behaviour is
     // preserved.
-    db.exec("PRAGMA busy_timeout = 30000");
+    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
     db.exec(`PRAGMA journal_mode = ${mode}`);
     if (opts.foreignKeys !== false) {
         db.exec("PRAGMA foreign_keys = ON");

package/dist/tasks/log-redaction.js

@@ -0,0 +1,156 @@
+// 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/.
+/**
+ * Decide which exact values must be scrubbed from a task's persisted run log
+ * (issue #755).
+ *
+ * # The gap
+ *
+ * All three task target kinds funnel through `persistRunLog`, which applied
+ * only `redactCredentialPatterns` — credential *shapes* (`Bearer …`, `sk-…`,
+ * webhook URLs). Prompt- and workflow-target runs additionally redact the exact
+ * secret values reachable by the run before their output ever reaches the log.
+ * Command-target runs did not: a scheduled command that echoed a configured
+ * secret whose value is not credential-shaped persisted it verbatim, into both
+ * the `.log` file and `logs.db`, for the whole retention window.
+ *
+ * # Why the obvious fix is wrong
+ *
+ * The issue proposed reusing {@link isEnvPassthroughValueSafeToExpose} — the
+ * filter the prompt path uses — over the env handed to the child. That filter
+ * fails CLOSED for any name outside a 22-entry allowlist, which is right where
+ * it currently runs: the prompt path filters `envPassthrough`, a short list the
+ * operator explicitly declared. A command task inherits the WHOLE ambient
+ * environment, so the same rule classifies essentially everything as secret.
+ * Measured on a developer machine: 127 of 132 variables, 25 of them with
+ * one-character values (`SHLVL=1`, `OLDPWD=/`, `GIT_TERMINAL_PROMPT=0`).
+ * Redaction is substring replacement, so those become live needles:
+ *
+ *     Build finished in 12.4s        ->  Build finished in [REDACTED]2.[REDACTED]s
+ *     3 tests passed, 0 failed       ->  [REDACTED] tests passed, [REDACTED] failed
+ *     wrote dist/index.js (48 KB)    ->  wrote dist[REDACTED]index.js ([REDACTED]8 KB)
+ *
+ * A fix that destroys every command log is not a fix.
+ *
+ * # What this does instead
+ *
+ * Three sources, and the distinction between them is the whole design:
+ *
+ *  1. **Declared by config** — the config names which variables hold
+ *     credentials (`engines.<n>.apiKey: ${VAR}`, `embedding.apiKey`, and the
+ *     implicit `AKM_ENGINE_<NAME>_API_KEY` / `AKM_LLM_API_KEY` /
+ *     `AKM_EMBED_API_KEY` recipes). akm KNOWS these are secret.
+ *  2. **Declared by the task** — the `redact:` list, names only.
+ *  3. **Inferred** — a name-shape heuristic over the remaining environment, for
+ *     the ambient credential akm was never told about.
+ *
+ * Only (3) is a guess, so only (3) carries {@link MIN_INFERRED_SECRET_LENGTH}.
+ * A declared secret is redacted at ANY length, because the operator told us
+ * what it is; applying a floor to declared values would silently stop redacting
+ * short secrets that are scrubbed today. The floor exists solely to stop a
+ * *guess* from mangling a log, and 8 clears every real credential format (AWS
+ * key id 20, GitHub PAT 40, `sk-…` 40+) while excluding the flags and counters
+ * that a name heuristic occasionally catches.
+ *
+ * Note what is deliberately NOT collected: the akm secret store on disk. A
+ * spawned command sees `process.env`, not akm's stores — a stored secret can
+ * only be echoed if it is already in the environment, where the rules above
+ * catch it by name. Walking every bundle's `secrets/` on each task firing would
+ * cost a recursive readdir plus an unbounded read for values the child cannot
+ * reach anyway. `redact:` is the escape hatch for a secret injected under a
+ * name none of the rules recognise.
+ */
+import { collectSensitiveValues, isEnvPassthroughValueSafeToExpose } from "../core/redaction.js";
+import { collectEngineCredentialValues } from "../integrations/agent/engine-resolution.js";
+/**
+ * Shortest value an INFERRED (name-heuristic) match may contribute as a
+ * redaction needle. Declared secrets bypass this entirely.
+ *
+ * Redaction replaces substrings, so a short needle is not merely useless — it
+ * corrupts unrelated output. Below 8 the noise tier is fully intact (`1`, `0`,
+ * `/`, `80`, `true`, `xhigh`, `31999`); at 8 a chance collision with ordinary
+ * log vocabulary is negligible, and every credential format in real use is far
+ * longer. It also matches the conventional minimum password length, so a
+ * secret shorter than this is already outside normal policy.
+ */
+export const MIN_INFERRED_SECRET_LENGTH = 8;
+/**
+ * Environment names whose VALUE is treated as a credential on shape alone.
+ *
+ * The keyword must be a whole `_`-delimited word. Anchoring on only one side
+ * would drag in ordinary configuration from whichever side is left open:
+ * a leading anchor alone matches `KEYBOARD_LAYOUT` and `AUTHOR`, a trailing one
+ * matches `MONKEY` and `BYPASS`. Whole-word matching gets `GH_TOKEN`,
+ * `NPM_AUTH_TOKEN`, `MY_API_KEY`, `DB_PASS` and `AWS_SECRET_ACCESS_KEY` right.
+ */
+const INFERRED_SECRET_NAME = /(?:^|_)(?:API_?KEY|KEY|TOKEN|SECRET|PASSWORD|PASSWD|PASS|CREDENTIALS?|AUTH)(?:_|$)/i;
+/**
+ * Credential variables whose name is a single glued word, which no
+ * word-boundary rule can see. Enumerated rather than matched: loosening the
+ * pattern enough to catch `PGPASSWORD` also catches `MONKEY`.
+ *
+ * `PWD` cannot be a keyword above for the same reason it appears here as part
+ * of `MYSQL_PWD` — on its own it is the working directory.
+ */
+const KNOWN_SECRET_NAMES = new Set(["PGPASSWORD", "MYSQL_PWD"]);
+/** True when the NAME alone marks this variable as holding a credential. */
+export function isInferredSecretName(name) {
+    return KNOWN_SECRET_NAMES.has(name.toUpperCase()) || INFERRED_SECRET_NAME.test(name);
+}
+/** Resolve `${VAR}` / `$VAR` to the variable NAME, or undefined for anything else. */
+function envRefName(spec) {
+    if (!spec)
+        return undefined;
+    const match = /^\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?$/.exec(spec.trim());
+    return match?.[1];
+}
+/**
+ * Every value that must be scrubbed from one task's persisted output.
+ *
+ * `declaredNames` comes from the task's `redact:` list. A name that is unset in
+ * `env` simply contributes nothing — naming a variable you do not currently
+ * export is not an error.
+ */
+export function collectTaskLogSensitiveValues(input) {
+    const { env, config, declaredNames } = input;
+    const values = new Set();
+    const addDeclared = (value) => {
+        if (value === undefined)
+            return;
+        const trimmed = value.trim();
+        // Both spellings: `resolveSecret` does not trim but `resolveCredentialFromEnv`
+        // does, so a variable with trailing whitespace reaches an output boundary in
+        // either form depending on which path materialized it.
+        if (value.length > 0)
+            values.add(value);
+        if (trimmed.length > 0)
+            values.add(trimmed);
+    };
+    // (1) Declared by config — engine credentials, via the collector the prompt
+    // path already uses, plus the embedding key it does not cover.
+    if (config) {
+        for (const value of collectEngineCredentialValues(config, env))
+            values.add(value);
+        addDeclared(env[envRefName(config.embedding?.apiKey) ?? "AKM_EMBED_API_KEY"]);
+    }
+    // (2) Declared by the task's `redact:` list — names only, never values.
+    for (const name of declaredNames ?? [])
+        addDeclared(env[name]);
+    // (3) Inferred from the name shape. The only guessing tier, so the only one
+    // with a length floor — and still subject to the value-level check that keeps
+    // an allowlisted name from being treated as secret.
+    for (const [name, value] of Object.entries(env)) {
+        if (value === undefined || value.length < MIN_INFERRED_SECRET_LENGTH)
+            continue;
+        if (!isInferredSecretName(name))
+            continue;
+        if (isEnvPassthroughValueSafeToExpose(name, value))
+            continue;
+        values.add(value);
+    }
+    // Expands credential-bearing URLs into their embedded components. Can yield
+    // needles shorter than the floor (a URL's password), which is correct: the
+    // operator's own value implied them.
+    return collectSensitiveValues(values);
+}

package/dist/tasks/parser.js

@@ -12,6 +12,10 @@
  * workflow: workflows/daily-backup
  * params:
  *   region: us-east-1
+ * timeoutMs: 3600000               # whole-run bound; omit for the unattended
+ *                                  # default, `null` to opt out entirely
+ * maxSteps: 20                     # optional run bounds, same as the
+ * maxRetries: 1                    # `akm workflow run` flags
  * # ...or:
  * prompt: agents/my-agent           # asset ref
  * # ...or:
@@ -27,6 +31,8 @@
  * description: …
  * when_to_use: …
  * tags: [scheduled, backup]
+ * redact: [ACME_DEPLOY_TOKEN]     # optional: env var NAMES (never values) to
+ *                                 # scrub from this task's persisted log
  * ```
  *
  * Validation lives in {@link validateTaskDocument}. The parser enforces the
@@ -38,7 +44,8 @@ import { parse as parseYaml } from "yaml";
 import { isFullRefInput } from "../core/asset/resolve-ref.js";
 import { UsageError } from "../core/errors.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
-import { TASK_SCHEMA_VERSION } from "./schema.js";
+import { WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_RETRIES } from "../workflows/resource-limits.js";
+import { TASK_MAX_REDACT_NAMES, TASK_MAX_TIMEOUT_MS, TASK_SCHEMA_VERSION, } from "./schema.js";
 import { validateTaskId } from "./task-id.js";
 export function parseTaskDocument(input) {
     const { yaml, filePath } = input;
@@ -79,15 +86,25 @@ export function parseTaskDocument(input) {
     }
     let target;
     if (hasWorkflow) {
-        rejectTargetFields(data, ["params"], id, filePath);
+        rejectTargetFields(data, ["params", "timeoutMs", "maxSteps", "maxRetries"], id, filePath);
         const ref = requireString(data.workflow, "workflow", filePath);
         if (!ref) {
             throw new UsageError(`Task "${id}" has empty \`workflow\`. File: ${filePath}`, "INVALID_FLAG_VALUE");
         }
+        // The three run bounds `akm workflow run` takes as flags, declared in the
+        // task file instead: an unattended run gets the same abort path the
+        // interactive CLI has. `timeoutMs` left unset falls back to the runner's
+        // default (see DEFAULT_WORKFLOW_TASK_TIMEOUT_MS); `null` opts out.
+        const workflowTimeoutMs = readTimeout(data.timeoutMs, filePath);
+        const maxSteps = readBoundedInteger(data.maxSteps, "maxSteps", 1, undefined, filePath);
+        const maxRetries = readBoundedInteger(data.maxRetries, "maxRetries", 0, WORKFLOW_MAX_RETRIES, filePath);
         target = {
             kind: "workflow",
             ref,
             params: readParams(data.params, filePath),
+            ...(workflowTimeoutMs !== undefined ? { timeoutMs: workflowTimeoutMs } : {}),
+            ...(maxSteps !== undefined ? { maxSteps } : {}),
+            ...(maxRetries !== undefined ? { maxRetries } : {}),
         };
     }
     else if (hasCommand) {
@@ -114,6 +131,7 @@ export function parseTaskDocument(input) {
         };
     }
     const timeoutMs = hasCommand ? readTimeout(data.timeoutMs, filePath) : undefined;
+    const redact = readRedactNames(data.redact, filePath);
     return {
         version: TASK_SCHEMA_VERSION,
         schemaVersion: TASK_SCHEMA_VERSION,
@@ -127,6 +145,7 @@ export function parseTaskDocument(input) {
         ...(tags ? { tags } : {}),
         source: { path: filePath },
         timeoutMs,
+        ...(redact ? { redact } : {}),
     };
 }
 const TASK_KEYS = new Set([
@@ -144,9 +163,22 @@ const TASK_KEYS = new Set([
     "engine",
     "model",
     "timeoutMs",
+    "maxSteps",
+    "maxRetries",
     "llm",
+    "redact",
+]);
+const SHARED_KEYS = new Set([
+    "version",
+    "name",
+    "description",
+    "when_to_use",
+    "tags",
+    "schedule",
+    "enabled",
+    // `redact:` is target-agnostic: every kind funnels through the same log sink.
+    "redact",
 ]);
-const SHARED_KEYS = new Set(["version", "name", "description", "when_to_use", "tags", "schedule", "enabled"]);
 function requireVersion(data, id, filePath) {
     if (data.version === TASK_SCHEMA_VERSION)
         return;
@@ -258,9 +290,54 @@ function readTimeout(value, filePath) {
         return undefined;
     if (value === null)
         return null;
-    if (typeof value === "number" && Number.isInteger(value) && value > 0)
+    // The ceiling is `setTimeout`'s, not a policy: a larger delay overflows and
+    // fires immediately, turning a generous timeout into an instant abort.
+    if (typeof value === "number" && Number.isInteger(value) && value > 0 && value <= TASK_MAX_TIMEOUT_MS)
         return value;
-    throw new UsageError(`Key "timeoutMs" must be a positive integer or null. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    throw new UsageError(`Key "timeoutMs" must be an integer from 1 through ${TASK_MAX_TIMEOUT_MS}, or null. File: ${filePath}`, "INVALID_FLAG_VALUE");
+}
+/**
+ * Read the `redact:` opt-in list — environment variable NAMES whose values are
+ * scrubbed from this task's persisted log (#755).
+ *
+ * A value that looks like a secret rather than a name is rejected outright, not
+ * silently accepted: a literal in a task file would be indexed, searchable and
+ * printed verbatim by `akm show`, so accepting one would leak the secret
+ * through a wider channel than the redaction closes.
+ */
+function readRedactNames(value, filePath) {
+    if (value === undefined || value === null)
+        return undefined;
+    const invalid = (detail) => {
+        throw new UsageError(`Key "redact" ${detail}. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    };
+    if (!Array.isArray(value))
+        return invalid("must be a list of environment variable names");
+    if (value.length > TASK_MAX_REDACT_NAMES) {
+        return invalid(`accepts at most ${TASK_MAX_REDACT_NAMES} names (got ${value.length})`);
+    }
+    const names = [];
+    for (const entry of value) {
+        if (typeof entry !== "string" || !WORKFLOW_ENV_VAR_NAME_PATTERN.test(entry)) {
+            return invalid(`takes environment variable NAMES only (matching ${WORKFLOW_ENV_VAR_NAME_PATTERN.source}), not values — ` +
+                `got ${JSON.stringify(entry)}. A secret written here would be indexed and printed by \`akm show\``);
+        }
+        if (!names.includes(entry))
+            names.push(entry);
+    }
+    return names.length > 0 ? names : undefined;
+}
+function readBoundedInteger(value, key, minimum, maximum, filePath) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value >= minimum &&
+        (maximum === undefined || value <= maximum)) {
+        return value;
+    }
+    const range = maximum === undefined ? `at least ${minimum}` : `from ${minimum} through ${maximum}`;
+    throw new UsageError(`Key "${key}" must be an integer ${range}. File: ${filePath}`, "INVALID_FLAG_VALUE");
 }
 function readLlmOverrides(value, filePath) {
     if (value === undefined)