akm-cli 0.9.0 → 0.9.1-beta.1

package/dist/indexer/indexer.js

@@ -7,6 +7,8 @@ import { detectAdapterId } from "../core/adapter/detect-adapter.js";
 import { adapterForId } from "../core/adapter/registry.js";
 import { isHttpUrl, toErrorMessage } from "../core/common.js";
 import { concurrentMap } from "../core/concurrent.js";
+import { isLoopbackEndpoint } from "../core/loopback.js";
+import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
 import { withStateDb } from "../core/state-db.js";
@@ -39,23 +41,15 @@ function throwIfAborted(signal) {
 export function getDefaultLlmConcurrency(llmConfig) {
     if (typeof llmConfig?.concurrency === "number")
         return llmConfig.concurrency;
-    if (!llmConfig?.endpoint)
-        return 1;
-    try {
-        const url = new URL(llmConfig.endpoint);
-        // URL.hostname keeps IPv6 brackets ("[::1]") — strip them so the loopback
-        // comparison actually matches.
-        const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
-        if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host.endsWith(".localhost"))
-            return 1;
-    }
-    catch {
+    // Local model servers stay at 1 (single loaded model; parallel requests
+    // trigger reload thrash); an absent or unparseable endpoint fails safe as
+    // local. ONE classifier decides what "local" means (`core/loopback.ts`,
+    // shared with the workflow engine's frozen concurrency default).
+    if (isLoopbackEndpoint(llmConfig?.endpoint))
         return 1;
-    }
     // Remote endpoints default to a modest 2-wide pool (owner ruling 2026-07-21):
     // enough to overlap request latency without hammering rate-limited APIs.
-    // Local model servers stay at 1 (single loaded model; parallel requests
-    // trigger reload thrash). The explicit-override branch above only fires for
+    // The explicit-override branch above only fires for
     // callers that put `concurrency` on the connection themselves —
     // `engines.<name>.concurrency` is a valid schema field but `resolveLlmEngineUse`
     // does NOT copy it into the resolved connection, so on the enrichment path the
@@ -290,12 +284,33 @@ export function reconcileBodyOpeningIndexState(db, flagEnabled, isFullWalk) {
  *
  * Only rows with a non-empty `file_path` are checked — remote/virtual entries
  * that have no local path are always skipped.
+ *
+ * "No longer exists" means ABSENT, never merely unreadable (#791). This pass
+ * DELETES rows, and `fs.existsSync` reported `false` for a file akm lacked
+ * permission to look at exactly as for one that had been removed — so a
+ * bundle temporarily mounted read-restricted (a uid mismatch, a tightened
+ * parent directory) had its whole index wiped, and the run reported the
+ * deletions as a clean success. Unreadable files keep their rows and are
+ * reported instead.
  */
 function runCleanPass(db, dryRun) {
     const allEntries = db.prepare("SELECT id, entry_key AS ref, file_path AS path FROM entries").all();
     // Only check entries that have a non-empty local path (skip remote/virtual).
     const localEntries = allEntries.filter((e) => typeof e.path === "string" && e.path.trim() !== "");
-    const missing = localEntries.filter((e) => !fs.existsSync(e.path));
+    const missing = [];
+    const unreadable = [];
+    for (const entry of localEntries) {
+        const { access, code } = classifyPathAccess(entry.path);
+        if (access === "absent")
+            missing.push(entry);
+        else if (access === "inaccessible")
+            unreadable.push({ path: entry.path, ...(code ? { code } : {}) });
+    }
+    if (unreadable.length > 0) {
+        const shown = unreadable.slice(0, 5).map((u) => describeInaccessiblePath(u.path, u.code));
+        warn(`Index clean pass kept ${unreadable.length} entr${unreadable.length === 1 ? "y" : "ies"} whose file akm cannot ` +
+            `read (unreadable is not deleted): ${shown.join("; ")}${unreadable.length > shown.length ? "; …" : ""}`);
+    }
     if (!dryRun && missing.length > 0) {
         deleteEntriesByIds(db, missing.map((e) => e.id));
     }
@@ -319,6 +334,24 @@ export async function akmIndex(options) {
         return akmIndexOverride(options);
     return akmIndexReal(options);
 }
+let indexTransactionHookForTests;
+/**
+ * TEST-ONLY. Observe the in-flight reindex transaction; `undefined` restores.
+ *
+ * Exists because the delete-then-reinsert atomicity guarantee is, by
+ * construction, invisible from outside the transaction: by the time
+ * `akmIndex()` resolves, the commit has already collapsed both generations
+ * into one observable state. Concurrency tests install a hook that opens a
+ * SECOND connection at these points and asserts it still sees the previous
+ * complete generation. Inert in production (one `undefined?.()` per reindex).
+ */
+export function _setIndexTransactionHookForTests(hook) {
+    indexTransactionHookForTests = hook;
+}
+/** Fire a named in-transaction observation point (no-op outside tests). */
+function indexTransactionHook(point) {
+    indexTransactionHookForTests?.(point);
+}
 /**
  * Detect an adapter for every resolvable source that does not declare one, and
  * persist each detection into `config.json`.
@@ -976,6 +1009,10 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
             // (cross-DB) nulls entry_ids that no longer resolve to a rebuilt entry and
             // re-resolves the rest by entry_ref — subsuming the old detach.
             db.exec("DELETE FROM entries");
+            // Atomicity observation point: inside the transaction the tables are now
+            // empty, but no other connection may observe that. See
+            // tests/integration/indexer/reindex-generation-atomicity.test.ts.
+            indexTransactionHook("full-delete-applied");
         }
         for (const { dirPath, currentStashDir, files, stash, skip, reason, hashByFile, conceptIdByFile, indexVariant, remove, pruneMissing, } of dirRecords) {
             if (remove) {
@@ -1089,6 +1126,9 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
                 }
             }
         }
+        // Atomicity observation point: the new generation is fully written but
+        // uncommitted, so it must still be invisible to other connections.
+        indexTransactionHook("records-persisted");
     });
     insertTransaction();
     deleteUsageEventsByEntryIds([...deletedUsageEntryIds]);

package/dist/indexer/passes/memory-inference.js

@@ -43,6 +43,7 @@ import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-r
 import { todayIso } from "../../core/common.js";
 import { concurrentMap } from "../../core/concurrent.js";
 import { warn } from "../../core/warn.js";
+import { recordWrittenPath } from "../../core/write-provenance.js";
 import { writeAssetToSource } from "../../core/write-source.js";
 import { isProcessEnabled } from "../../llm/feature-gate.js";
 import { resolveIndexPassLLM } from "../../llm/index-passes.js";
@@ -449,6 +450,9 @@ function markParentProcessed(parent) {
     const next = assembleAsset(updatedFm, block.content);
     try {
         fs.writeFileSync(parent.filePath, next, "utf8");
+        // #652: the parent's `inference_processed` stamp is a real asset mutation
+        // (the documented writeAssetToSource exception above) — journal it.
+        recordWrittenPath(parent.filePath);
     }
     catch (err) {
         warn(`memory inference: failed to mark parent processed ${parent.filePath}: ${err instanceof Error ? err.message : String(err)}`);

package/dist/indexer/search/db-search.js

@@ -1,27 +1,15 @@
 // 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/.
-/**
- * Database-backed (SQLite + FTS5/vector) source search implementation.
- *
- * Extracted from source-search.ts to break the circular import:
- *   source-search.ts → sources/providers/filesystem.ts → db-search.ts (no cycle)
- *
- * source-search.ts imports this module for the `searchLocal` export.
- * sources/providers/filesystem.ts also imports `searchLocal` from here.
- *
- * Renamed from `local-search.ts` to signal that this is the DB-layer search
- * implementation, not a "local vs. remote" distinction.
- */
-import fs from "node:fs";
 import path from "node:path";
 import { buildActionFromContributors, defaultActionContributors } from "../../core/action-contributors.js";
 import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { displayRef } from "../../core/asset/resolve-ref.js";
+import { classifyPathAccess } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
 import { defaultRendererRegistry } from "../../core/type-presentation.js";
 import { warn } from "../../core/warn.js";
-import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { assertIndexPathReadable, closeDatabase, openExistingDatabase, } from "../../storage/repositories/index-connection.js";
 import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getPositiveFeedbackCountsByIds, } from "../../storage/repositories/index-entries-repository.js";
 import { searchFts } from "../../storage/repositories/index-fts-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
@@ -158,7 +146,12 @@ export async function searchLocal(input) {
     // reads serve the existing index as-is.
     await ensureIndex(stashDir);
     const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath)) {
+    // An index we cannot READ is not an index that does not exist (#791). Saying
+    // "No search index available" for a populated index the caller merely lacks
+    // permission on is a lie at exit 0 — and an agent consuming this JSON has no
+    // way to tell it from a genuine empty result, so it relays the lie onward.
+    assertIndexPathReadable(dbPath);
+    if (classifyPathAccess(dbPath).access === "absent") {
         return {
             hits: [],
             tip: "No search index available. Run 'akm index' to build one.",

package/dist/integrations/agent/engine-resolution.js

@@ -43,6 +43,29 @@ function resolveCredential(name, engine, config) {
         ? { names: [specific, "AKM_LLM_API_KEY"], required: false }
         : { names: [specific], required: false };
 }
+/**
+ * Read a credential descriptor's value out of `process.env`: the FIRST
+ * non-empty trimmed value across `names`, in declared order. A `required`
+ * descriptor that resolves to nothing is a config error naming its PRIMARY
+ * variable — the one an operator is told to set.
+ *
+ * The ONE env-credential seam. The live-config dispatch boundary
+ * ({@link materializeLlmConnection}) and the FROZEN workflow dispatch boundary
+ * (`materializeFrozenLlm` in `workflows/exec/unit-dispatch.ts`, whose frozen
+ * snapshots carry a structurally identical descriptor) both read through it, so
+ * lookup order and the failure message cannot drift between them.
+ */
+export function resolveCredentialFromEnv(credential) {
+    for (const name of credential?.names ?? []) {
+        const candidate = process.env[name]?.trim();
+        if (candidate)
+            return candidate;
+    }
+    if (credential?.required) {
+        throw new ConfigError(`Required engine credential ${credential.names[0]} is not set.`, "INVALID_CONFIG_FILE");
+    }
+    return undefined;
+}
 /** Collect materialized engine credentials for output and persistence redaction. */
 export function collectEngineCredentialValues(config, envSource = process.env) {
     const values = new Set();
@@ -112,17 +135,7 @@ export function materializeLlmConnection(resolved) {
             throw new ConfigError(formatExtraParamsIssue(`Engine "${resolved.engine}" extraParams`, issue), "INVALID_CONFIG_FILE");
         }
     }
-    let apiKey;
-    for (const name of resolved.credential?.names ?? []) {
-        const candidate = process.env[name]?.trim();
-        if (candidate) {
-            apiKey = candidate;
-            break;
-        }
-    }
-    if (resolved.credential?.required && !apiKey) {
-        throw new ConfigError(`Required engine credential ${resolved.credential.names[0]} is not set.`, "INVALID_CONFIG_FILE");
-    }
+    const apiKey = resolveCredentialFromEnv(resolved.credential);
     return {
         ...resolved.connection,
         ...(apiKey ? { apiKey } : {}),

package/dist/integrations/agent/model-aliases.js

@@ -13,7 +13,7 @@
 const BUILTIN_ALIASES = [
     {
         // Anthropic's Mythos-class tier above Opus — the recommended resolution
-        // target for the `deep` workflow tier (see docs/reference/workflows.md).
+        // target for the `deep` workflow tier (see docs/reference/workflow-schema.md).
         alias: "fable",
         platforms: {
             claude: "claude-fable-5",

package/dist/integrations/agent/profiles.js

@@ -1,13 +1,21 @@
 // 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/.
+/**
+ * Built-in profile registry for external agent CLIs (v1 spec §12.1).
+ *
+ * A `AgentProfile` is the minimum metadata required to shell-out to a
+ * coding-agent CLI. Named engines lower canonical harness metadata into this
+ * intentionally small internal shape. The wrapper is in `./spawn.ts`.
+ */
+import { COMMON_SPAWN_ENV_PASSTHROUGH } from "../../core/spawn-env.js";
 // AKM_EVENT_SOURCE carries usage-event provenance (improve/task) so that akm
 // invocations a spawned agent makes are recorded as machine traffic, not user
 // demand (DRIFT-6). Without it in the passthrough whitelist, buildChildEnv drops
 // the stamp at the agent boundary — e.g. `akm wiki ingest` spawns an agent whose
 // `akm curate/show/search` tool-calls then log source='user', silently inflating
 // every lane's read-back (GRR). It is a provenance tag, never a secret.
-const COMMON_PASSTHROUGH = ["HOME", "PATH", "USER", "LANG", "LC_ALL", "TERM", "TMPDIR", "AKM_EVENT_SOURCE"];
+const COMMON_PASSTHROUGH = COMMON_SPAWN_ENV_PASSTHROUGH;
 /**
  * Built-in profiles for the agent CLIs akm knows out of the box: the five the
  * v1 spec calls out explicitly, plus the P2 harness adapters (copilot, pi,

package/dist/integrations/agent/spawn.js

@@ -14,90 +14,21 @@
  * NEVER imports an LLM SDK. Agents are reachable only via shell-out;
  * this is a pre-emptive guarantee against the #222 invariant.
  */
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
-import { runManagedSubprocess, } from "../../core/subprocess.js";
+import { collectAllowlistedEnv } from "../../core/spawn-env.js";
+import { runManagedSubprocess, streamCaptureFailure, } from "../../core/subprocess.js";
 import { getCommandBuilder } from "./builders.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
-/**
- * Supplement `existingPath` with well-known user binary directories when
- * running in a scheduler context (cron/launchd) where PATH is stripped.
- *
- * Detection heuristic: if the current PATH does not contain the user's home
- * directory, we are likely in a stripped scheduler env. In an interactive
- * shell the user's home almost always appears (e.g. ~/.bun/bin, ~/.cargo/bin).
- *
- * Only directories that actually exist on disk are prepended, and only if
- * they are not already present, so interactive-shell PATH ordering is never
- * disturbed.
- */
-export function supplementPathForSchedulerContext(existingPath) {
-    const home = os.homedir();
-    // If PATH already contains the home directory, we are in an interactive
-    // shell — skip supplementation entirely.
-    if (existingPath.split(path.delimiter).some((d) => d.startsWith(home))) {
-        return existingPath;
-    }
-    const candidates = pathCandidatesForCurrentPlatform(home);
-    const existing = new Set(existingPath.split(path.delimiter).filter(Boolean));
-    const toAdd = candidates.filter((d) => !existing.has(d) && fs.existsSync(d));
-    if (toAdd.length === 0)
-        return existingPath;
-    return [...toAdd, existingPath].filter(Boolean).join(path.delimiter);
-}
-function pathCandidatesForCurrentPlatform(home) {
-    if (process.platform === "win32") {
-        // Windows: Bun + Cargo + Scoop + Chocolatey + system tools. Order favors
-        // user-local installs over machine-global so the user's chosen toolchain
-        // wins. These paths are commonly stripped from Task Scheduler / service
-        // environments, mirroring the cron/launchd problem on POSIX.
-        const localAppData = process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
-        const userProfile = process.env.USERPROFILE ?? home;
-        const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
-        return [
-            path.join(userProfile, ".bun", "bin"),
-            path.join(localAppData, "Programs", "bun"),
-            path.join(userProfile, ".cargo", "bin"),
-            path.join(localAppData, "Programs", "Git", "cmd"),
-            path.join(userProfile, "scoop", "shims"),
-            path.join(programFiles, "Git", "cmd"),
-            "C:\\ProgramData\\chocolatey\\bin",
-        ];
-    }
-    return [
-        path.join(home, ".bun", "bin"),
-        path.join(home, ".cargo", "bin"),
-        path.join(home, ".local", "bin"),
-        "/opt/homebrew/bin",
-        "/opt/homebrew/sbin",
-        "/usr/local/bin",
-    ];
-}
 /**
  * Build the child env. Starts empty and copies through:
- *   • Every name in `profile.envPassthrough`.
+ *   • Every name in `profile.envPassthrough` (via the shared
+ *     {@link collectAllowlistedEnv}, which also supplements PATH for
+ *     scheduler contexts where the inherited PATH is stripped).
  *   • Every entry in `profile.env`.
  *   • Every entry in `options.env` (highest precedence).
- *
- * PATH is supplemented with well-known user binary directories when running
- * in a scheduler context (cron/launchd) where the inherited PATH is stripped.
- * See {@link supplementPathForSchedulerContext}.
  */
 function buildChildEnv(profile, options) {
-    const source = options.envSource ?? process.env;
-    const env = {};
-    for (const name of profile.envPassthrough) {
-        const value = source[name];
-        if (value !== undefined)
-            env[name] = value;
-    }
-    // Supplement PATH after passthrough so the scheduler-context fix applies to
-    // the value actually coming from the environment source.
-    if (env.PATH !== undefined) {
-        env.PATH = supplementPathForSchedulerContext(env.PATH);
-    }
+    const env = collectAllowlistedEnv(profile.envPassthrough, options.envSource ?? process.env);
     if (profile.env) {
         for (const [k, v] of Object.entries(profile.env))
             env[k] = v;
@@ -108,19 +39,16 @@ function buildChildEnv(profile, options) {
     }
     return env;
 }
+/**
+ * This path's phrasing of the SHARED incomplete-capture verdict
+ * ({@link streamCaptureFailure} in `core/subprocess.ts`). The classification
+ * lives in the primitive so the agent path and the workflow `exec` path cannot
+ * drift apart on what "the capture did not complete" means; only the sentence
+ * naming the profile is local. Message text is unchanged from the inlined copy.
+ */
 function streamFailureMessage(profileName, stdout, stderr) {
-    const failures = [];
-    if (stdout.error)
-        failures.push(`stdout read failed: ${stdout.error instanceof Error ? stdout.error.message : String(stdout.error)}`);
-    if (stderr.error)
-        failures.push(`stderr read failed: ${stderr.error instanceof Error ? stderr.error.message : String(stderr.error)}`);
-    if (stdout.timedOut)
-        failures.push("stdout drain timed out");
-    if (stderr.timedOut)
-        failures.push("stderr drain timed out");
-    if (failures.length === 0)
-        return undefined;
-    return `agent CLI "${profileName}" output capture failed: ${failures.join("; ")}`;
+    const failures = streamCaptureFailure(stdout, stderr);
+    return failures === undefined ? undefined : `agent CLI "${profileName}" output capture failed: ${failures}`;
 }
 /**
  * Spawn the agent CLI described by `profile` with `prompt` (forwarded as

package/dist/integrations/lockfile.js

@@ -7,6 +7,7 @@ import { writeFileAtomic } from "../core/common.js";
 import { ConfigError, rethrowIfTestIsolationError } from "../core/errors.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../core/file-lock.js";
 import { acquireMaintenanceBarrier } from "../core/maintenance-barrier.js";
+import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDataDir, getLockfileLockPath, getLockfilePath } from "../core/paths.js";
 // ── Lock sentinel ────────────────────────────────────────────────────────────
 const LOCK_MAX_RETRIES = 3;
@@ -54,6 +55,29 @@ export function readLockfile() {
         return [];
     }
 }
+/**
+ * Refuse to treat an UNREADABLE lockfile (or data dir) as an absent one (#791).
+ *
+ * Every write path here is read-modify-WRITE: it loads the current entries and
+ * writes the whole array back. An unreadable `akm.lock` that reads as `[]`
+ * therefore does not merely lose information — the very next
+ * `writeFileAtomic` replaces the operator's entire lock record with the single
+ * entry this call happened to be adding. That is the same catastrophe R-012
+ * guards against for a *corrupt* file, reached instead through a permission
+ * fault, and `fs.existsSync`/a swallowed `readFileSync` could not tell the two
+ * apart from "the file was never created".
+ *
+ * No-op when the path is genuinely absent — that case really does have nothing
+ * to preserve.
+ */
+function assertLockfilePathReadable(target) {
+    const { access, code } = classifyPathAccess(target);
+    if (access !== "inaccessible")
+        return;
+    throw new ConfigError(`Refusing to modify the lockfile: ${describeInaccessiblePath(target, code)}. akm cannot read the existing lock ` +
+        "records, and writing over them would destroy every bundle they track. Fix the ownership or mode of that " +
+        "path (or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user owns) and retry.", "DATA_DIR_UNREADABLE");
+}
 /**
  * Like {@link readLockfile}, but THROWS instead of silently degrading to `[]`
  * when the on-disk lockfile exists yet is not parseable JSON or not a JSON
@@ -82,7 +106,15 @@ function readLockfileOrThrow() {
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
-        return []; // File does not exist (or is otherwise unreadable) — nothing to preserve.
+        // "Missing file" is the only failure with nothing to preserve. An
+        // UNREADABLE lockfile has everything to preserve and we cannot see it —
+        // degrading it to `[]` here is precisely the destructive overwrite this
+        // function was written to prevent, only triggered by a permission fault
+        // instead of a corrupt file (#791). Classify AFTER the failed read so the
+        // happy path costs no extra syscall and the answer describes the failure
+        // we actually got.
+        assertLockfilePathReadable(lockfilePath);
+        return [];
     }
     let parsed;
     try {
@@ -172,6 +204,11 @@ export async function upsertLockEntry(entry) {
 function readLockEntriesForMigration() {
     let existing = [];
     const lockfilePath = getLockfilePath();
+    // `mergeLockEntriesSync` writes `existing` straight back out, so an
+    // unreadable lockfile read as absent would be overwritten with just the
+    // migrator's sparse entries (#791). This is also what
+    // `assertMigrationLockfileReadable` promises to have checked.
+    assertLockfilePathReadable(lockfilePath);
     if (fs.existsSync(lockfilePath)) {
         let raw;
         try {
@@ -211,7 +248,13 @@ export function mergeLockEntriesSync(entries) {
     writeLockfileUnlocked([...existing.filter((e) => !incomingIds.has(e.id)), ...merged]);
 }
 export async function removeLockEntry(id) {
-    if (!fs.existsSync(getDataDir()))
+    // Returning early says "there is no lock record to remove", and the uninstall
+    // that called us reports success on that basis. Only an absent data dir earns
+    // it — one we cannot read may hold the very entry we were asked to drop, and
+    // silently leaving it behind is how a bundle stays "installed" forever (#791).
+    const dataDir = getDataDir();
+    assertLockfilePathReadable(dataDir);
+    if (!fs.existsSync(dataDir))
         return;
     const release = await acquireLockSentinel();
     try {

package/dist/output/text/lint-format.js

@@ -16,9 +16,18 @@ function glyphFor(fixed) {
         return { glyph: "✓", severityRank: 2 };
     return { glyph: "⚠", severityRank: 1 };
 }
+/**
+ * `file:line` when the finding is line-anchored (workflow parse/compile
+ * errors), bare `file` otherwise. `LintIssue.line` is optional precisely
+ * because most lint sources are whole-file, so their headline is byte-identical
+ * to what it has always been.
+ */
+function locationOf(issue) {
+    return typeof issue.line === "number" ? `${issue.file}:${issue.line}` : issue.file;
+}
 function issueEntry(issue) {
     const { glyph, severityRank } = glyphFor(issue.fixed);
-    return { severityRank, glyph, headline: `${issue.file}  [${issue.issue}]  ${issue.detail}` };
+    return { severityRank, glyph, headline: `${locationOf(issue)}  [${issue.issue}]  ${issue.detail}` };
 }
 function renderIssueSection(title, issues) {
     if (issues.length === 0)
@@ -30,14 +39,18 @@ export function formatLintPlain(r) {
         return null;
     const fixed = Array.isArray(r.fixed) ? r.fixed : [];
     const flagged = Array.isArray(r.flagged) ? r.flagged : [];
+    const warnings = Array.isArray(r.warnings) ? r.warnings : [];
     const summary = r.summary;
     const lines = [];
     if (typeof r.ok === "boolean")
         lines.push(`ok: ${r.ok}`);
-    lines.push(`summary: fixed=${summary?.fixed ?? fixed.length} flagged=${summary?.flagged ?? flagged.length}`);
-    // Flagged (still needs attention) surfaces before fixed (already handled)
-    // so a scan of the output hits the actionable items first.
+    lines.push(`summary: fixed=${summary?.fixed ?? fixed.length} flagged=${summary?.flagged ?? flagged.length}` +
+        ` warnings=${summary?.warnings ?? warnings.length}`);
+    // Flagged (still needs attention) surfaces before warnings (advisory,
+    // non-fatal) and fixed (already handled), so a scan of the output hits the
+    // actionable items first.
     lines.push("", ...renderIssueSection("flagged", flagged));
+    lines.push("", ...renderIssueSection("warnings", warnings));
     lines.push("", ...renderIssueSection("fixed", fixed));
     return lines.join("\n").trim();
 }