akm-cli 0.9.15 → 0.9.16-alpha.2

package/dist/commands/tasks/validate.js

@@ -9,23 +9,18 @@
  * a bundle/adapter/concept id at all — it reads exactly the path it was
  * given and classifies it.
  *
- * Reuses the exact version-routing shim `parseTaskSource`
- * (`src/tasks/source/parse-task-source.ts`) already applies for every other
- * task-source reader (`akm task sync`'s `compileTaskSources` included) —
- * this module never forks a second parser or a second v2/v3 migration
- * planner. `readBoundedTaskSourceYaml` / `peekTaskSourceVersion` / `own` are
- * the SAME front-end helpers that shim itself calls first; they are used
- * here only to recover the file's ORIGINALLY DECLARED schema version for
- * the report, because `parseTaskSource`'s own `ParsedTaskSource.version` is
- * always `4` post-shim — it cannot answer "was this a v2/v3/v4 file?" on
- * its own once a v2/v3 source has been converted in memory.
+ * Reuses the exact current-schema router `parseTaskSource`
+ * (`src/tasks/source/parse-task-source.ts`) used by every other task-source
+ * reader. Historical v2/v3 documents are deliberately rejected here and
+ * point to `akm migrate apply`; validation does not embed a second legacy
+ * parser or perform an in-memory migration.
  *
  * Beyond parsing, this module also runs the SAME two per-source gates
  * `akm task sync`'s `compileTaskSources` runs before it ever installs a
  * schedule — `assertTaskScheduleInputsSatisfyContract` and
  * `assertTaskScheduleCronValid` (both extracted from `scheduler-sync.ts` for
  * exactly this reuse) — so a file `sync` would reject can never
- * be reported `valid`/`converts` here. Cron dialect is checked against
+ * be reported `valid` here. Cron dialect is checked against
  * `backendNameForPlatform()`, the same platform default `sync` falls back
  * to whenever it has no injected/native-inspected backend to hand (see
  * `akmTasksAdd`, `src/commands/tasks/tasks.ts`); a bare file was never
@@ -48,19 +43,12 @@
  * table in its header, extended for the two gates above):
  *   - `valid`       — parses as task source v4 directly (declared `version: 4`)
  *                      and passes both sync gates.
- *   - `converts`    — declared `version: 2` or `3`; the deterministic
- *                      in-memory migrator produced a valid v4 document that
- *                      passes both sync gates.
- *   - `blocked`     — declared `version: 2` or `3`; the migrator itself
- *                      could not convert it (an ambiguous/unmigratable
- *                      shape) — the ONLY way `parseTaskSource` ever throws
- *                      for those two version numbers, so no message-text
- *                      sniffing is needed to tell this apart from `invalid`.
+ *   - `blocked`     — declared `version: 2` or `3`; runtime does not accept
+ *                      it and the explicit migrator must rewrite it first.
  *   - `invalid`     — the document declares SOME version (`4`, or anything
  *                      other than 2/3/4) but fails to parse/validate, OR it
- *                      parsed (directly or via a SUCCESSFUL v2/v3
- *                      conversion) but fails one of the two sync gates
- *                      above, OR the YAML itself does not parse at all
+ *                      parsed but fails one of the two sync gates above, OR
+ *                      the YAML itself does not parse at all
  *                      (a genuine syntax error, not merely a non-task
  *                      shape) — reported with the parser's own reason.
  *   - `not-a-task`  — the document parses as YAML but never declares a
@@ -138,11 +126,14 @@ export async function akmTaskValidate(filePath) {
         if (!(cause instanceof UsageError))
             throw cause;
         const reason = cause.message;
-        // `parseTaskSource` only ever throws for a declared version 2/3 via the
-        // unmigratable-conversion branch (see this file's header) — no separate
-        // message check needed to recognize "blocked" here.
         if (declaredVersion === 2 || declaredVersion === 3) {
-            return { ok: false, path: resolvedPath, sourceVersion: declaredVersion, outcome: "blocked", reason };
+            return {
+                ok: false,
+                path: resolvedPath,
+                sourceVersion: declaredVersion,
+                outcome: "blocked",
+                reason: `${reason} Run \`akm migrate apply --dry-run\`, review the plan, then run \`akm migrate apply\`.`,
+            };
         }
         if (peekFailed) {
             return { ok: false, path: resolvedPath, outcome: "invalid", reason };
@@ -161,11 +152,8 @@ export async function akmTaskValidate(filePath) {
     // Success is unreachable from any path that leaves `declaredVersion`
     // undefined — the router requires a numeric 2/3/4 version to reach here.
     const sourceVersion = declaredVersion ?? 4;
-    // The document itself parsed (directly, or via a successful v2/v3
-    // conversion) — now the two gates `compileTaskSources` runs before
-    // accepting it. A violation here is `invalid`, never `blocked`: the
-    // migrator already succeeded, so this is the same kind of defect a
-    // native v4 document with the identical schedule would have.
+    // The current document parsed; now run the two gates `compileTaskSources`
+    // applies before accepting it.
     try {
         assertTaskScheduleInputsSatisfyContract(parsed.v4, resolvedPath);
         assertTaskScheduleCronValid(parsed.v4, backend);
@@ -180,7 +168,7 @@ export async function akmTaskValidate(filePath) {
         ok: true,
         path: resolvedPath,
         sourceVersion,
-        outcome: sourceVersion === 2 || sourceVersion === 3 ? "converts" : "valid",
+        outcome: "valid",
         resolved: buildResolved(id, parsed.v4),
     };
 }

package/dist/core/activation-policy.js

@@ -22,7 +22,7 @@ const INTERACTIVE_TOOL_ENV_KEYS = new Set(["EDITOR", "VISUAL", "PAGER"]);
  * genuine RCE-class key; first-party stashes warn. The interactive-tool
  * group (see {@link INTERACTIVE_TOOL_ENV_KEYS}) only ever warns, since akm's
  * own env-injection path never invokes those keys as a command. An explicit
- * `--allow-insecure` (threaded through by the caller, same override
+ * `--allow-dangerous-env-keys` (threaded through by the caller, same override
  * `decideDangerousKeyInstall`'s `"warn-allow"` already honors for rule 2)
  * downgrades a remaining block to a warning too — the operator is not racing
  * themselves. See rule 1 above.
@@ -31,7 +31,7 @@ const INTERACTIVE_TOOL_ENV_KEYS = new Set(["EDITOR", "VISUAL", "PAGER"]);
  *   (already filtered by the caller via `isDangerousEnvKey`).
  * @param thirdParty `true` when the env's source is a third-party stash — i.e.
  *   its origin carries a `registryId`.
- * @param allowInsecure `true` when the operator passed `--allow-insecure` (or
+ * @param allowDangerousEnvKeys `true` when the operator passed `--allow-dangerous-env-keys` (or
  *   its equivalent) for this injection. Defaults to `false`.
  */
 export function decideDangerousEnvInjection(input) {
@@ -39,7 +39,7 @@ export function decideDangerousEnvInjection(input) {
         return "allow";
     if (!input.thirdParty)
         return "warn";
-    if (input.allowInsecure)
+    if (input.allowDangerousEnvKeys)
         return "warn";
     const onlyInteractiveTool = input.dangerousKeys.every((key) => INTERACTIVE_TOOL_ENV_KEYS.has(key));
     return onlyInteractiveTool ? "warn" : "block";
@@ -53,7 +53,7 @@ export function decideDangerousEnvInjection(input) {
 export function decideDangerousKeyInstall(input) {
     if (!input.findingsPresent)
         return "allow";
-    return input.allowInsecure ? "warn-allow" : "gate";
+    return input.allowDangerousEnvKeys ? "warn-allow" : "gate";
 }
 // ── Rule 3: write activation (search-source.ts, installations.ts) ────────────
 /**

package/dist/core/adapter/adapters/akm-adapter.js

@@ -130,6 +130,11 @@ function akmStashAbstains(root, absPath) {
     const segments = relPath.split(/[\\/]+/).filter(Boolean);
     if (segments.length === 0)
         return false;
+    // A bundle's root README describes the bundle itself; it is not an AKM
+    // knowledge asset. Nested README files remain adapter-owned documentation
+    // and are handled by the normal typed-directory matcher policy.
+    if (segments.length === 1 && segments[0]?.toLowerCase() === "readme.md")
+        return true;
     // Skip env `.env` files that have a sibling `.sensitive` marker file.
     if (segments[0] === "env" && (absPath.endsWith(".env") || path.basename(absPath) === ".env")) {
         if (fs.existsSync(absPath.replace(/\.env$/, ".sensitive")))

package/dist/core/adapter/execution-source.js

@@ -127,15 +127,6 @@ function nullableString(value, path) {
 function nullableObject(value, path) {
     return value === null ? null : cloneExecutionJsonObject(value, path);
 }
-function nullableEnvironment(value, path) {
-    if (value === null)
-        return null;
-    const environment = cloneExecutionJsonObject(value, path);
-    if (Object.values(environment).some((entry) => typeof entry !== "string")) {
-        throw new TypeError(`${path} values must be strings`);
-    }
-    return environment;
-}
 function nullableTimeout(value, path) {
     const timeout = cloneExecutionJson(value, path);
     if (timeout !== null && typeof timeout !== "string" && typeof timeout !== "number") {
@@ -167,6 +158,16 @@ export function executionDefaultsFromFrontmatter(data, options) {
     const namespace = own(frontmatter, "akm")
         ? requireMetadataMapping(frontmatter.akm, "frontmatter.akm")
         : snapshotStrictRecord({}, "frontmatter.akm");
+    for (const key of ["workspace", "environment", "runtime"]) {
+        const location = own(frontmatter, key)
+            ? `frontmatter.${key}`
+            : own(namespace, key)
+                ? `frontmatter.akm.${key}`
+                : undefined;
+        if (location) {
+            throw new TypeError(`${location} is host-controlled and cannot be declared by an executable asset; configure the selected engine or workflow execution environment instead`);
+        }
+    }
     const out = Object.create(null);
     if (kind === "command" && own(frontmatter, "agent")) {
         out.agent = nullableString(frontmatter.agent, "frontmatter.agent");
@@ -269,26 +270,6 @@ export function executionDefaultsFromFrontmatter(data, options) {
             ? topLevelTimeouts.get(selectedTimeoutKey)
             : namespacedTimeouts.get(selectedTimeoutKey);
     }
-    for (const key of ["workspace", "environment", "runtime"]) {
-        const namespaced = own(namespace, key)
-            ? key === "workspace"
-                ? nullableString(namespace[key], `frontmatter.akm.${key}`)
-                : key === "environment"
-                    ? nullableEnvironment(namespace[key], `frontmatter.akm.${key}`)
-                    : nullableObject(namespace[key], `frontmatter.akm.${key}`)
-            : undefined;
-        const topLevel = allowTopLevelEngine && own(frontmatter, key)
-            ? key === "workspace"
-                ? nullableString(frontmatter[key], `frontmatter.${key}`)
-                : key === "environment"
-                    ? nullableEnvironment(frontmatter[key], `frontmatter.${key}`)
-                    : nullableObject(frontmatter[key], `frontmatter.${key}`)
-            : undefined;
-        if (topLevel !== undefined)
-            out[key] = topLevel;
-        else if (namespaced !== undefined)
-            out[key] = namespaced;
-    }
     return out;
 }
 function snapshotRendererInput(input) {

package/dist/core/config/config-schema.js

@@ -29,28 +29,29 @@
  *   typo in an optional section.
  * - Unsupported top-level source shapes and provider kinds are hard-rejected;
  *   silently dropping them would mask user data loss.
- * - UNKNOWN-KEY POLICY: object schemas use passthrough (unknown keys are
- *   preserved and ignored, NOT rejected). akm runs across multiple installed
- *   versions sharing one config.json; a newer version writes keys an older
- *   version's schema doesn't know yet, so hard-rejecting unknown keys turned
- *   benign version skew into `INVALID_CONFIG_FILE` failures. Known keys are
- *   still type-checked; passthrough preserves unknown keys across a
- *   load→save round trip so an older reader never strips a newer writer's
- *   settings. (Replaced the prior strict-mode object walls.)
+ * - UNKNOWN-KEY POLICY: portable descriptive sections generally use
+ *   passthrough so version skew round-trips newer settings. Small finite
+ *   authority/toggle sections (`scheduler`, `execution`, `experimental`, and
+ *   reranker policy) are strict: a misspelling there must not silently turn a
+ *   safety decision off. The top level remains passthrough and warns on
+ *   unknown keys.
  * - `defaultWriteTarget` resolution and similar cross-field invariants are
  *   enforced at save time via `superRefine` on the top-level schema.
  */
 import { z } from "zod";
+import { bundleRefToString, parseBundleRef } from "../asset/asset-ref.js";
 import { warnOnce } from "../warn.js";
 import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "./engine-semantics.js";
 import { EmbeddingConnectionConfigSchema } from "./schema/embedding.js";
 import { EnginesSchema } from "./schema/engines.js";
+import { ExecutionPolicyConfigSchema } from "./schema/execution.js";
 import { ExperimentalConfigSchema } from "./schema/experimental.js";
 import { FeedbackConfigSchema } from "./schema/feedback.js";
 import { ImproveConfigSchema } from "./schema/improve.js";
 import { IndexConfigSchema } from "./schema/index-config.js";
 import { OutputConfigSchema } from "./schema/output.js";
 import { CURRENT_CONFIG_VERSION, engineName, nonEmptyString, nonNegativeNumber } from "./schema/primitives.js";
+import { SchedulerConfigSchema } from "./schema/scheduler.js";
 import { SearchConfigSchema } from "./schema/search.js";
 import { SetupConfigSchema } from "./schema/setup.js";
 import { BundlesConfigSchema, RegistryConfigEntrySchema } from "./schema/sources-bundles.js";
@@ -65,6 +66,7 @@ export { ConsolidateProcessConfigSchema, DistillProcessConfigSchema, ExtractProc
 export { IndexConfigSchema, IndexPassConfigSchema } from "./schema/index-config.js";
 export { OutputConfigSchema } from "./schema/output.js";
 export { CURRENT_CONFIG_VERSION, LlmInvocationOverridesSchema } from "./schema/primitives.js";
+export { SchedulerActivationSchema, SchedulerConfigSchema } from "./schema/scheduler.js";
 export { SearchConfigSchema } from "./schema/search.js";
 export { SetupConfigSchema } from "./schema/setup.js";
 export { BundleConfigEntrySchema, BundlesConfigSchema, RegistryConfigEntrySchema, SourceConfigEntrySchema, } from "./schema/sources-bundles.js";
@@ -107,6 +109,8 @@ export const AkmConfigShape = {
     defaults: DefaultsSchema.optional(),
     semanticSearchMode: z.enum(["off", "auto"]).default("off"),
     embedding: EmbeddingConnectionConfigSchema.optional(),
+    // Host-local execution authority. Inherited layers are stripped.
+    execution: ExecutionPolicyConfigSchema.optional(),
     index: IndexConfigSchema.optional(),
     registries: z.array(RegistryConfigEntrySchema).optional(),
     // `bundles` + `defaultBundle` are the only source configuration shape. The
@@ -122,6 +126,9 @@ export const AkmConfigShape = {
     archiveRetentionDays: nonNegativeNumber.optional(),
     improve: ImproveConfigSchema.optional(),
     workflow: WorkflowConfigSchema.optional(),
+    // Host-local scheduler grants. Inherited layers are stripped by
+    // `resolveExtendsChain`; bundle-provided config never activates code.
+    scheduler: SchedulerConfigSchema.optional(),
     setup: SetupConfigSchema.optional(),
     // D8 — explicit opt-ins for behaviour outside the stability contract. Every
     // key defaults to OFF; see `src/core/config/experimental.ts` for the readers.
@@ -168,6 +175,55 @@ export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) =>
                 message: `defaultBundle "${config.defaultBundle}" does not name a configured bundle`,
             });
         }
+        else if (config.bundles[config.defaultBundle]?.enabled === false) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["defaultBundle"],
+                message: `defaultBundle "${config.defaultBundle}" is disabled`,
+            });
+        }
+    }
+    if (config.defaultWriteTarget !== undefined) {
+        const target = config.bundles?.[config.defaultWriteTarget];
+        if (!target) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["defaultWriteTarget"],
+                message: `defaultWriteTarget "${config.defaultWriteTarget}" does not name a configured bundle`,
+            });
+        }
+        else if (target.enabled === false) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["defaultWriteTarget"],
+                message: `defaultWriteTarget "${config.defaultWriteTarget}" is disabled`,
+            });
+        }
+    }
+    const activationKeys = new Set();
+    for (const [index, activation] of (config.scheduler?.enabled ?? []).entries()) {
+        try {
+            const parsed = parseBundleRef(activation.ref);
+            if (!parsed.bundle || parsed.fragment !== undefined || bundleRefToString(parsed) !== activation.ref) {
+                throw new Error("not canonical");
+            }
+            const key = `${activation.kind}\0${activation.ref}`;
+            if (activationKeys.has(key)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["scheduler", "enabled", index],
+                    message: "duplicates an earlier scheduler activation",
+                });
+            }
+            activationKeys.add(key);
+        }
+        catch {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["scheduler", "enabled", index, "ref"],
+                message: "must be one canonical fully-qualified ref without a fragment",
+            });
+        }
     }
     for (const key of ["llm", "agent", "improve"]) {
         if (config.defaults && key in config.defaults) {

package/dist/core/config/config-sources.js

@@ -6,6 +6,7 @@
  * values from the current bundle map in an {@link AkmConfig}.
  */
 import { createHash } from "node:crypto";
+import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../errors.js";
 /** The current one-component-per-bundle configuration entry, if present. */
@@ -33,6 +34,87 @@ export function bundleComponentConfig(bundle) {
 export function bundleContentRoot(entryPath, componentRoot) {
     return path.resolve(entryPath, componentRoot ?? ".");
 }
+/**
+ * Physical identity for an already materialized filesystem bundle.
+ *
+ * Configuration may spell the same directory through relative paths or
+ * symbolic links. Those spellings are not distinct sources: treating them as
+ * distinct would make ownership, default-source trust, and scheduler grants
+ * depend on syntax instead of the directory the OS will actually read.
+ */
+export function bundlePhysicalContentRoot(entryPath, componentRoot) {
+    const resolved = bundleContentRoot(entryPath, componentRoot);
+    try {
+        return fs.realpathSync.native(resolved);
+    }
+    catch (cause) {
+        // Cache-backed sources can be configured before they are materialized.
+        // Their source descriptor remains the identity until a real path exists.
+        if (cause.code === "ENOENT")
+            return resolved;
+        throw new ConfigError(`Unable to resolve physical bundle root ${JSON.stringify(resolved)}: ${cause instanceof Error ? cause.message : String(cause)}`, "INVALID_CONFIG_FILE");
+    }
+}
+/** Whether a configured bundle participates in reads, writes, and execution. */
+export function isBundleEnabled(config, bundleId) {
+    const bundle = config.bundles?.[bundleId];
+    return bundle !== undefined && bundle.enabled !== false;
+}
+/**
+ * Stable identity of the origin currently installed under a bundle id.
+ *
+ * This deliberately excludes mutable policy (`enabled`, `writable`,
+ * credentials, adapter selection) and bundle contents. Ordinary updates and
+ * adapter auto-detection for the same origin keep their grant; changing the
+ * locator or component root does not.
+ */
+export function bundleSourceId(config, bundleId) {
+    const bundle = config.bundles?.[bundleId];
+    if (!bundle) {
+        throw new ConfigError(`Bundle ${JSON.stringify(bundleId)} is not configured.`, "INVALID_CONFIG_FILE");
+    }
+    const component = bundleComponentConfig(bundle);
+    let source;
+    if (bundle.path !== undefined) {
+        source = { kind: "filesystem", locator: bundlePhysicalContentRoot(bundle.path, component?.root) };
+    }
+    else if (bundle.git !== undefined) {
+        source = { kind: "git", locator: normalizeInstalledGitRef("git", bundle.git) };
+    }
+    else if (bundle.website !== undefined) {
+        // Crawl/refresh settings are mutable fetch policy, not source identity.
+        // Changing them must not silently revoke a user's scheduling decision for
+        // the same website origin.
+        source = { kind: "website", url: bundle.website.url };
+    }
+    else if (bundle.npm !== undefined) {
+        source = { kind: "npm", locator: bundle.npm };
+    }
+    else {
+        throw new ConfigError(`Bundle ${JSON.stringify(bundleId)} has no source descriptor.`, "INVALID_CONFIG_FILE");
+    }
+    return hashBundleSourceIdentity({
+        version: 1,
+        source,
+        registryId: bundle.registryId ?? null,
+        componentRoot: component?.root ?? ".",
+    });
+}
+/** Identity for an environment-only filesystem bundle not persisted in config. */
+export function filesystemBundleSourceId(contentRoot) {
+    return hashBundleSourceIdentity({
+        version: 1,
+        source: { kind: "filesystem", locator: bundlePhysicalContentRoot(contentRoot) },
+        registryId: null,
+        componentRoot: ".",
+    });
+}
+function hashBundleSourceIdentity(identity) {
+    return `sha256:${createHash("sha256")
+        .update("akm.bundle-source\0v1\0")
+        .update(JSON.stringify(identity))
+        .digest("hex")}`;
+}
 /**
  * The resolved primary stash path — the `defaultBundle`'s filesystem `path`
  * (spec §10.1) — or `undefined` when no filesystem primary is configured.
@@ -68,13 +150,20 @@ export function bundleContentRoots(config) {
     for (const [id, entry] of Object.entries(bundles)) {
         if (typeof entry.path !== "string" || entry.path.length === 0)
             continue;
-        out.push({ id, contentRoot: bundleContentRoot(entry.path, bundleComponentConfig(entry)?.root) });
+        out.push({ id, contentRoot: bundlePhysicalContentRoot(entry.path, bundleComponentConfig(entry)?.root) });
     }
     return out;
 }
 /** The bundle id whose resolved content root already matches `resolvedContentRoot`, if any. */
 export function bundleKeyForContentRoot(config, resolvedContentRoot) {
-    return bundleContentRoots(config).find((entry) => entry.contentRoot === resolvedContentRoot)?.id;
+    let physical = path.resolve(resolvedContentRoot);
+    try {
+        physical = fs.realpathSync.native(physical);
+    }
+    catch {
+        // Compare the unresolved absolute locator when the candidate is not yet materialized.
+    }
+    return bundleContentRoots(config).find((entry) => entry.contentRoot === physical)?.id;
 }
 export function bundlesToSourceEntries(config) {
     const bundles = config.bundles;
@@ -96,6 +185,7 @@ export function bundleEntryToSourceEntry(key, bundle, isPrimary = false) {
     const base = {
         name: key,
         ...(bundle.writable !== undefined ? { writable: bundle.writable } : {}),
+        ...(bundle.credential !== undefined ? { credential: bundle.credential } : {}),
         ...(bundle.enabled !== undefined ? { enabled: bundle.enabled } : {}),
         ...(isPrimary ? { primary: true } : {}),
     };
@@ -235,6 +325,10 @@ export function resolveConfiguredSources(config) {
     }
     return out;
 }
+/** Active sources in the same deterministic order as `resolveConfiguredSources`. */
+export function resolveActiveConfiguredSources(config) {
+    return resolveConfiguredSources(config).filter((source) => source.enabled !== false);
+}
 function toConfiguredSource(persisted, isPrimary) {
     const source = parseSourceSpec(persisted);
     if (!source)