@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.8

package/packages/agentsam-repository/src/tickets.js

@@ -31,7 +31,11 @@ export function createTicketId() {
 }
 
 /**
- * Generate SQL for ticket creation with mandatory agentsam_agent_run when active.
+ * Generate SQL for ticket creation.
+ *
+ * Goal state and execution state are separate nouns. Creating/activating a
+ * ticket must not fabricate an agentsam_agent_run. Callers may link an
+ * already-created real run explicitly via agentRunId.
  */
 export function generateTicketCreateSql({
   accountId,
@@ -59,16 +63,7 @@ export function generateTicketCreateSql({
   if (!tTitle) throw new Error('title_required');
 
   const statements = [];
-  let runId = clean(agentRunId);
-
-  if (status === 'active' && !runId) {
-    runId = createAgentRunId();
-    statements.push(`INSERT INTO agentsam_agent_run (
-  id, account_id, mode, status, started_at_unix, created_at_unix, updated_at_unix
-) VALUES (
-  ${sqlText(runId)}, ${sqlText(account)}, 'agent', 'running', ${sqlInt(now)}, ${sqlInt(now)}, ${sqlInt(now)}
-);`);
-  }
+  const runId = clean(agentRunId);
 
   statements.push(`INSERT INTO agentsam_tickets (
   id, title, description, status, status_reason, project, subsystem,
@@ -98,12 +93,15 @@ export function generateTicketCreateSql({
 }
 
 /**
- * Generate SQL to activate a ticket and wire a real agentsam_agent_run row.
+ * Generate SQL to activate a ticket.
+ *
+ * agentRunId is optional and must reference a run created by the execution
+ * subsystem. Activation itself never creates a run.
  */
 export function generateTicketActivationSql({
   accountId,
   ticketId,
-  agentRunId = createAgentRunId(),
+  agentRunId = null,
   statusReason = null,
   now = Math.floor(Date.now() / 1000),
 }) {
@@ -111,18 +109,13 @@ export function generateTicketActivationSql({
   const tid = clean(ticketId);
   if (!account) throw new Error('account_id_required');
   if (!tid) throw new Error('ticket_id_required');
-  const runId = clean(agentRunId) || createAgentRunId();
+  const runId = clean(agentRunId);
 
   const statements = [
-    `INSERT INTO agentsam_agent_run (
-  id, account_id, mode, status, started_at_unix, created_at_unix, updated_at_unix
-) VALUES (
-  ${sqlText(runId)}, ${sqlText(account)}, 'agent', 'running', ${sqlInt(now)}, ${sqlInt(now)}, ${sqlInt(now)}
-);`,
     `UPDATE agentsam_tickets SET
   status = 'active',
   status_reason = ${sqlText(statusReason)},
-  agent_run_id = COALESCE(agent_run_id, ${sqlText(runId)}),
+  agent_run_id = COALESCE(${sqlText(runId || null)}, agent_run_id),
   updated_at = ${sqlInt(now)},
   closed_at = NULL
 WHERE id = ${sqlText(tid)};`,
@@ -130,14 +123,14 @@ WHERE id = ${sqlText(tid)};`,
   id, ticket_id, event_type, from_status, to_status, detail, actor_type, created_at
 ) VALUES (
   'tke_' || lower(hex(randomblob(8))), ${sqlText(tid)}, 'status_change', 'backlog', 'active',
-  'activated_with_agent_run', 'agentsam_sdk', ${sqlInt(now)}
+  'activated', 'agentsam_sdk', ${sqlInt(now)}
 );`,
   ];
 
   return {
     sql: statements.join('\n\n'),
     ticketId: tid,
-    agentRunId: runId,
+    agentRunId: runId || null,
   };
 }
 

package/packages/agentsam-repository/test/goap-tickets-workspace-state.test.mjs

@@ -30,7 +30,7 @@ test('generateTicketCreateSql requires account_id and title', () => {
   assert.throws(() => generateTicketCreateSql({ accountId: 'acc_1' }), /title_required/);
 });
 
-test('generateTicketCreateSql with status=active mints an agent_run and links it on the ticket insert', () => {
+test('generateTicketCreateSql with status=active does not fabricate an agent run', () => {
   const { sql, ticketId, agentRunId } = generateTicketCreateSql({
     accountId: 'acc_1',
     title: 'Wire GOAP planner',
@@ -38,12 +38,10 @@ test('generateTicketCreateSql with status=active mints an agent_run and links it
     now: 1000,
   });
   assert.ok(ticketId.startsWith('tkt_'));
-  assert.ok(agentRunId && agentRunId.startsWith('arun_'));
-  assert.match(sql, /INSERT INTO agentsam_agent_run/);
+  assert.equal(agentRunId, null);
+  assert.doesNotMatch(sql, /INSERT INTO agentsam_agent_run/);
   assert.match(sql, /INSERT INTO agentsam_tickets/);
   assert.match(sql, /INSERT INTO agentsam_ticket_events/);
-  const runOccurrences = sql.split(agentRunId).length - 1;
-  assert.ok(runOccurrences >= 2, 'agent_run id should appear in both the run insert and the ticket insert');
 });
 
 test('generateTicketCreateSql with status=backlog does not mint an agent_run', () => {
@@ -83,16 +81,29 @@ test('generateTicketActivationSql requires account and ticket id', () => {
   assert.throws(() => generateTicketActivationSql({ accountId: 'a' }), /ticket_id_required/);
 });
 
-test('generateTicketActivationSql wires a fresh agent_run and clears closed_at', () => {
+test('generateTicketActivationSql changes focus without fabricating an agent run', () => {
   const { sql, agentRunId } = generateTicketActivationSql({
     accountId: 'acc_1',
     ticketId: 'tkt_abc',
     now: 1000,
   });
-  assert.ok(agentRunId.startsWith('arun_'));
+  assert.equal(agentRunId, null);
+  assert.doesNotMatch(sql, /INSERT INTO agentsam_agent_run/);
   assert.match(sql, /status = 'active'/);
   assert.match(sql, /closed_at = NULL/);
-  assert.match(sql, /COALESCE\(agent_run_id,/);
+  assert.match(sql, /agent_run_id = COALESCE\(NULL, agent_run_id\)/);
+});
+
+test('generateTicketActivationSql can link a run created by the execution subsystem', () => {
+  const { sql, agentRunId } = generateTicketActivationSql({
+    accountId: 'acc_1',
+    ticketId: 'tkt_abc',
+    agentRunId: 'arun_real',
+    now: 1000,
+  });
+  assert.equal(agentRunId, 'arun_real');
+  assert.doesNotMatch(sql, /INSERT INTO agentsam_agent_run/);
+  assert.match(sql, /agent_run_id = COALESCE\('arun_real', agent_run_id\)/);
 });
 
 test('generateTicketCloseSql maps shipped -> completed and abandoned/blocked -> failed run status', () => {

package/packages/connectors/cloudflare/package.json

@@ -18,5 +18,7 @@
   },
   "files": [
     "src"
-  ]
+  ],
+  "description": "Portable Cloudflare capability connector for AgentSam applications and SDK consumers.",
+  "license": "MIT"
 }

package/packages/identity/tests/lane1-packed-consumer.test.mjs

@@ -18,7 +18,7 @@ function run(cmd, args, cwd) {
   // for nested project installs. Strip that inherited allowance in the child only.
   const env = { ...process.env };
   for (const key of Object.keys(env)) {
-    if (/^npm_config_allow[_-]scripts$/i.test(key)) delete env[key];
+    if (/^npm_config_(?:allow[_-]?scripts|dry[_-]?run)$/i.test(key)) delete env[key];
   }
   return execFileSync(cmd, args, {
     cwd,

package/python/agentsam_sdk/repository/intelligence/discovery.py

@@ -10,6 +10,11 @@ DEFAULT_FALLBACK_EXCLUDE_DIRS = frozenset(
     {
         ".git",
         "node_modules",
+        "python_modules",
+        ".agentsam",
+        ".wrangler",
+        "vendor",
+        "target",
         "dist",
         "build",
         "coverage",
@@ -21,6 +26,25 @@ DEFAULT_FALLBACK_EXCLUDE_DIRS = frozenset(
     }
 )
 
+
+
+DEFAULT_EVIDENCE_NOISE_DIRS = frozenset(DEFAULT_FALLBACK_EXCLUDE_DIRS)
+DEFAULT_EVIDENCE_NOISE_SUFFIXES = (".min.js", ".bundle.js", ".map")
+
+
+def is_default_evidence_noise_path(value: str) -> bool:
+    path = str(value or "").replace("\\", "/").strip("/")
+    if not path:
+        return False
+    parts = path.split("/")
+    if any(part in DEFAULT_EVIDENCE_NOISE_DIRS for part in parts[:-1]):
+        return True
+    name = parts[-1]
+    if name in DEFAULT_EVIDENCE_NOISE_DIRS:
+        return True
+    lowered = name.lower()
+    return lowered.endswith(DEFAULT_EVIDENCE_NOISE_SUFFIXES)
+
 LANGUAGE_BY_EXT = {
     ".js": "JavaScript", ".mjs": "JavaScript", ".cjs": "JavaScript", ".jsx": "JavaScript",
     ".ts": "TypeScript", ".tsx": "TypeScript", ".py": "Python", ".go": "Go",
@@ -79,8 +103,9 @@ def active_paths(
     """Return active paths and discovery source (`git` or `filesystem`)."""
     paths = _git_paths(repo_root)
     if paths:
-        return paths, "git"
-    return _walk_paths(repo_root, fallback_exclude_dir_names), "filesystem"
+        return [path for path in paths if not is_default_evidence_noise_path(path)], "git"
+    walked = _walk_paths(repo_root, fallback_exclude_dir_names)
+    return [path for path in walked if not is_default_evidence_noise_path(path)], "filesystem"
 
 
 def _line_count(path: Path) -> int | None:

package/python/agentsam_sdk/repository/intelligence/git.py

@@ -6,6 +6,8 @@ from collections import Counter, defaultdict
 from pathlib import Path
 from typing import Any
 
+from .discovery import is_default_evidence_noise_path
+
 
 def run_git(repo_root: Path, *args: str) -> str:
     try:
@@ -56,6 +58,8 @@ def git_churn(repo_root: Path, *, days: int = 30) -> dict[str, dict[str, int]]:
         if len(parts) != 3:
             continue
         added_raw, deleted_raw, path = parts
+        if is_default_evidence_noise_path(path):
+            continue
         if added_raw == "-" or deleted_raw == "-":
             continue
         try:

package/python/tests/test_repository_intelligence.py

@@ -65,5 +65,35 @@ class TestRepositoryIntelligence(unittest.TestCase):
             self.assertTrue(any(row["path"] == "src/a.py" for row in snapshot["hot_files"]))
 
 
+    def test_default_evidence_noise_never_becomes_architecture_pressure(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            subprocess.run(["git", "init"], cwd=root, check=True, capture_output=True)
+            subprocess.run(["git", "config", "user.email", "fixture@example.com"], cwd=root, check=True)
+            subprocess.run(["git", "config", "user.name", "Fixture"], cwd=root, check=True)
+            (root / "src").mkdir()
+            (root / "python_modules").mkdir()
+            (root / ".agentsam" / "machine").mkdir(parents=True)
+            (root / "dist").mkdir()
+            (root / "src" / "app.js").write_text("export const app = 1;\n", encoding="utf-8")
+            (root / "python_modules" / "vendor.py").write_text("x = 1\n" * 100, encoding="utf-8")
+            (root / ".agentsam" / "machine" / "receipt.json").write_text("{}", encoding="utf-8")
+            (root / "dist" / "app.bundle.js").write_text("x" * 5000, encoding="utf-8")
+            subprocess.run(["git", "add", "-f", "."], cwd=root, check=True)
+            subprocess.run(["git", "commit", "-m", "fixture"], cwd=root, check=True, capture_output=True)
+
+            paths, _ = active_paths(root)
+            self.assertIn("src/app.js", paths)
+            self.assertNotIn("python_modules/vendor.py", paths)
+            self.assertNotIn(".agentsam/machine/receipt.json", paths)
+            self.assertNotIn("dist/app.bundle.js", paths)
+
+            snapshot = build_snapshot(root, churn_days=30, top=20)
+            pressure = {row["path"] for row in snapshot["pressure_points"]}
+            self.assertFalse(any(path.startswith("python_modules") for path in pressure))
+            self.assertFalse(any(path.startswith(".agentsam") for path in pressure))
+            self.assertFalse(any(path.startswith("dist") for path in pressure))
+
+
 if __name__ == "__main__":
     unittest.main()

package/src/cli/command-catalog.js

@@ -14,6 +14,7 @@ export const CLI_COMMAND_CATALOG = Object.freeze([
   { id: 'dev', summary: 'Run this project’s npm dev script', topic: 'work', skill: 'agentsam-app-fundamentals' },
   { id: 'inspect', summary: 'Bounded repository inspect / authority view', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'repository.inspect', common: true },
   { id: 'machine', summary: 'Deterministic local machine perception (inspect / asset discovery)', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'machine.inspect', common: true },
+  { id: 'package', summary: 'Audit, verify, and plan publication of distributable packages', topic: 'work', skill: 'agentsam-progression-guard', operation: 'package.audit', common: true, usage: ['agentsam package audit [--public] [--offline] [--json]', 'agentsam package status <name> [--offline] [--json]', 'agentsam package verify <name> [--offline] [--json]', 'agentsam package publish-plan [--offline] [--json]'] },
   { id: 'capabilities', summary: 'Inspect capability contracts', topic: 'create', skill: 'agentsam-app-fundamentals' },
   {
     id: 'setup',
@@ -93,7 +94,7 @@ export const CLI_COMMAND_CATALOG = Object.freeze([
   { id: 'init', summary: 'Knowledge setup or local scaffold', topic: 'create', skill: 'agentsam-app-fundamentals' },
   { id: 'codebaseindex', aliases: ['ingest', 'codebase-index'], summary: 'Guided codebase ingest: materials, allowlist, embeddings, storage', topic: 'work', skill: 'agentsam-codebaseindex', operation: 'codebaseindex.ingest', common: true },
   { id: 'brand', summary: 'Deterministic brand intelligence', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'brand.scan' },
-  { id: 'plan', summary: 'Composable plans (e.g. brand)', topic: 'work', skill: 'agentsam-app-fundamentals' },
+  { id: 'plan', summary: 'Durable project-local work plans + domain plans', topic: 'work', skill: 'agentsam-app-fundamentals' },
   { id: 'security', aliases: ['sca'], summary: 'Dependency + trust-boundary scan', topic: 'work', skill: 'agentsam-progression-guard', operation: 'security.scan', common: true },
   { id: 'merkle', summary: 'File integrity snapshots and explorer', topic: 'work', skill: 'agentsam-app-fundamentals' },
   { id: 'cad', summary: 'Blender/OpenSCAD/FreeCAD CAD tools', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'cad.blender.inspect' },

package/src/cli.js

@@ -25,12 +25,14 @@ import { runStatus } from './commands/status.js';
 import { runInteractive } from './commands/interactive.js';
 import { runShell } from './commands/shell.js';
 import { runGoap } from './commands/goap.js';
-import { runBrand, runPlan } from './commands/brand.js';
+import { runBrand } from './commands/brand.js';
+import { runPlan } from './commands/plan.js';
 import { runDockerize } from './commands/dockerize.js';
 import { runMini } from './commands/mini.js';
 import { runMerkle } from './commands/merkle.js';
 import { runDeployReceipt } from './commands/deploy-receipt.js';
 import { runSecurity } from './commands/security.js';
+import { runPackage } from './commands/package.js';
 import { runRecon } from './commands/recon.js';
 import { runCad } from './commands/cad.js';
 import { runMachine } from './commands/machine.js';
@@ -728,6 +730,13 @@ if (command === '--version' || command === '-v') {
     reportCliError(e);
     process.exitCode = 1;
   }
+} else if (command === 'package') {
+  try {
+    await runPackage(rest);
+  } catch (e) {
+    reportCliError(e);
+    process.exitCode = 1;
+  }
 } else if (command === 'security' || command === 'sca') {
   await runSecurity(rest);
 } else if (command === 'skills') {

package/src/commands/goap-world.js

@@ -0,0 +1,134 @@
+import { buildRepositoryAuditPacket } from '../agent/repository-audit.js';
+import { repositorySnapshot } from '../capabilities/repository-snapshot.js';
+import { getNextPlanStep, getPlan, openPlanLedger } from './plan-ledger.js';
+import { projectGoapWorld } from '../../packages/agentsam-goap/src/world.js';
+
+const PRIORITY_TO_TICKET = Object.freeze({
+  critical: 'P0',
+  high: 'P1',
+  medium: 'P2',
+  low: 'P3',
+});
+
+function stableJson(value) {
+  if (Array.isArray(value)) return '[' + value.map(stableJson).join(',') + ']';
+  if (value && typeof value === 'object') {
+    return '{' + Object.keys(value).sort().map((key) => JSON.stringify(key) + ':' + stableJson(value[key])).join(',') + '}';
+  }
+  return JSON.stringify(value);
+}
+
+export function knowledgeFreshness(snapshot = {}) {
+  const knowledge = snapshot.knowledge || {};
+  if (!knowledge.configured) return { status: 'not_configured', reason: 'knowledge_config_missing' };
+  if (!knowledge.indexed) return { status: 'not_indexed', reason: 'active_generation_missing' };
+  const receipt = knowledge.receipt || {};
+  if (receipt.scope && knowledge.scope && stableJson(receipt.scope) !== stableJson(knowledge.scope)) {
+    return { status: 'stale', reason: 'scope_policy_changed' };
+  }
+  if (receipt.merkle_root && snapshot.tree?.merkle_root && receipt.merkle_root !== snapshot.tree.merkle_root) {
+    return { status: 'stale', reason: 'repository_merkle_changed' };
+  }
+  return { status: 'current', reason: 'active_generation_matches_world' };
+}
+
+export async function buildLocalGoapState({ cwd = process.cwd(), snapshot = null } = {}) {
+  const ctx = openPlanLedger(cwd);
+  try {
+    const plan = getPlan(ctx, 'current');
+    if (!plan) return null;
+
+    const running = (plan.tasks || []).find((task) => task.status === 'running') || null;
+    const next = running ? null : getNextPlanStep(ctx, { planId: plan.id });
+    const step = running || next?.step || null;
+    const world = snapshot || await repositorySnapshot({ cwd: ctx.root });
+    const packet = buildRepositoryAuditPacket({
+      snapshot: world,
+      focus: [plan.title, step?.title].filter(Boolean),
+      requestedSections: ['repository', 'tree', 'knowledge', 'packages'],
+      evidenceBudget: 6000,
+    });
+    const freshness = knowledgeFreshness(world);
+    const projectedWorld = projectGoapWorld({
+      repository: {
+        ...world.repository,
+        merkle_root: world.tree?.merkle_root || null,
+      },
+      plan,
+      activeTodo: step,
+      knowledge: {
+        ...freshness,
+        generation_id: world.knowledge?.generation_id || null,
+      },
+      evidence: packet,
+      updatedAt: step?.updated_at_unix || plan.updated_at_unix || null,
+    });
+    const run = step?.agent_run_id
+      ? ctx.db.prepare('SELECT * FROM agentsam_agent_run WHERE id = ? LIMIT 1').get(step.agent_run_id) || null
+      : null;
+
+    const git = {
+      root: ctx.root,
+      repoFullName: world.repository?.full_name || ctx.git?.repoFullName || null,
+      revisionSha: world.repository?.revision_sha || ctx.git?.revisionSha || null,
+      branch: world.repository?.branch || ctx.git?.branch || null,
+      dirty: world.repository?.dirty ?? ctx.git?.dirty ?? null,
+    };
+    const activeTicket = step ? {
+      id: step.id,
+      title: step.title,
+      status: step.status,
+      priority: PRIORITY_TO_TICKET[step.priority] || 'P2',
+      subsystem: step.metadata?.kind || 'work',
+      surface: 'local',
+      status_reason: 'selected_from_project_local_plan',
+      description: step.description || null,
+      agent_run_id: step.agent_run_id || null,
+    } : {
+      id: plan.id,
+      title: plan.title,
+      status: plan.tasks_done === plan.tasks_total ? 'complete' : 'active',
+      priority: 'P2',
+      subsystem: 'plan',
+      surface: 'local',
+      status_reason: 'plan_has_no_open_executable_step',
+      agent_run_id: null,
+    };
+
+    return {
+      ok: true,
+      source: 'local_world',
+      repositoryId: world.repository?.repository_id || ctx.repositoryId,
+      git,
+      workspaceState: {
+        current_task_id: step?.id || null,
+        locked_by: 'project_local_plan',
+        checkpoint_sha: plan.metadata?.revision || null,
+        last_agent_action: 'world_snapshot_projected',
+        updated_at: step?.updated_at_unix || plan.updated_at_unix || null,
+      },
+      activeTicket,
+      agentRun: run,
+      recentCommits: [],
+      checkpoint: null,
+      cursor: {},
+      steps: plan.tasks || [],
+      stepsUnavailable: false,
+      localPlan: plan,
+      localStep: step,
+      worldSnapshot: {
+        snapshot_id: world.snapshot_id,
+        content_hash: world.content_hash,
+        merkle_root: world.tree?.merkle_root || null,
+        knowledge_generation_id: world.knowledge?.generation_id || null,
+        knowledge_freshness: freshness,
+        repository: world.repository,
+        actions: projectedWorld.actions,
+      },
+      boundedEvidence: packet,
+      canonicalWorld: projectedWorld,
+    };
+  } finally {
+    ctx.close();
+  }
+}

package/src/commands/goap.js

@@ -11,6 +11,7 @@ import {
   renderGoapPlan,
 } from '../../packages/agentsam-repository/src/goap.js';
 import { readAccountSession } from '../lib/account-session.js';
+import { buildLocalGoapState } from './goap-world.js';
 
 function parseArgs(args = []) {
   const flags = { _: [] };
@@ -102,7 +103,7 @@ export async function runGoap(subcommand = 'status', options = {}) {
     console.log(`Successfully created and activated GOAP goal: ${res.ticketId}`);
     console.log(`  Title:     ${res.title}`);
     console.log(`  Priority:  ${res.priority} [Subsystem: ${res.subsystem}]`);
-    console.log(`  Agent Run: ${res.agentRunId}`);
+    if (res.agentRunId) console.log(`  Agent Run: ${res.agentRunId}`);
     return;
   }
 
@@ -147,9 +148,15 @@ export async function runGoap(subcommand = 'status', options = {}) {
     return;
   }
 
-  const state = await readGoapState({ cwd, accountId });
-  if (!state.ok) {
-    console.error(`Error reading GOAP state: ${state.error || 'unknown error'}`);
+  let state = null;
+  try {
+    state = await buildLocalGoapState({ cwd });
+  } catch (error) {
+    if (jsonMode && options.debug) console.error(error?.stack || error);
+  }
+  if (!state && accountId) state = await readGoapState({ cwd, accountId });
+  if (!state?.ok) {
+    console.error(`Error reading GOAP state: ${state?.error || 'no local plan or remote GOAP state available'}`);
     return;
   }
 

package/src/commands/machine-binary.js

@@ -1,16 +1,18 @@
 /**
  * Resolve the agentsam-machine native binary.
  * Preference order:
- *   1. AGENTSAM_MACHINE_BIN
- *   2. agentsam-machine on PATH
- *   3. Built binary under native/agentsam-machine/target/{release,debug}
- *   4. cargo run --manifest-path … (dev fallback inside the SDK repo)
+ *   1. AgentSam-managed user runtime under ~/.agentsam/runtimes/machine
+ *   2. AGENTSAM_MACHINE_BIN explicit override
+ *   3. agentsam-machine on PATH
+ *   4. Built binary under native/agentsam-machine/target/{release,debug}
+ *   5. cargo run --manifest-path (SDK contributor fallback)
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { findExecutable, managedMachineResolution } from './machine-runtime.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const sdkRoot = path.resolve(here, '../..');
@@ -18,7 +20,7 @@ const machineCrate = path.join(sdkRoot, 'native/agentsam-machine');
 const machineManifest = path.join(machineCrate, 'Cargo.toml');
 
 /**
- * @typedef {{ kind: 'binary', path: string, source: string } | { kind: 'cargo', manifest: string, source: string } | { kind: 'missing', tried: string[] }} MachineBinaryResolution
+ * @typedef {{ kind: 'binary', path: string, source: string, version?: string } | { kind: 'cargo', manifest: string, source: string } | { kind: 'missing', tried: string[] }} MachineBinaryResolution
  */
 
 /**
@@ -27,6 +29,17 @@ const machineManifest = path.join(machineCrate, 'Cargo.toml');
 export function resolveMachineBinary(env = process.env) {
   const tried = [];
 
+  const managed = managedMachineResolution(env);
+  tried.push(...managed.tried);
+  if (managed.available) {
+    return {
+      kind: 'binary',
+      path: managed.path,
+      source: 'managed-runtime',
+      version: managed.state.current_version,
+    };
+  }
+
   const explicit = String(env.AGENTSAM_MACHINE_BIN || '').trim();
   if (explicit) {
     tried.push(explicit);
@@ -35,25 +48,25 @@ export function resolveMachineBinary(env = process.env) {
     }
   }
 
-  const pathHit = which('agentsam-machine');
-  if (pathHit) {
-    return { kind: 'binary', path: pathHit, source: 'PATH' };
-  }
+  const pathHit = findExecutable('agentsam-machine', env);
+  if (pathHit) return { kind: 'binary', path: pathHit, source: 'PATH' };
   tried.push('PATH:agentsam-machine');
 
   for (const rel of ['target/release/agentsam-machine', 'target/debug/agentsam-machine']) {
     const candidate = path.join(machineCrate, rel);
     tried.push(candidate);
     if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
-      return { kind: 'binary', path: candidate, source: rel.includes('release') ? 'crate-release' : 'crate-debug' };
+      return {
+        kind: 'binary',
+        path: candidate,
+        source: rel.includes('release') ? 'crate-release' : 'crate-debug',
+      };
     }
   }
 
   if (fs.existsSync(machineManifest)) {
-    const cargo = which('cargo');
-    if (cargo) {
-      return { kind: 'cargo', manifest: machineManifest, source: 'cargo-run' };
-    }
+    const cargo = findExecutable('cargo', env);
+    if (cargo) return { kind: 'cargo', manifest: machineManifest, source: 'cargo-run' };
     tried.push('cargo');
   }
 
@@ -62,7 +75,7 @@ export function resolveMachineBinary(env = process.env) {
 
 /**
  * @param {MachineBinaryResolution} resolution
- * @param {string[]} machineArgv  args after `agentsam machine` (e.g. ['inspect', './site', '--json'])
+ * @param {string[]} machineArgv
  * @param {{ stdio?: import('node:child_process').StdioOptions, env?: NodeJS.ProcessEnv }} [options]
  */
 export function spawnMachine(resolution, machineArgv, options = {}) {
@@ -73,6 +86,7 @@ export function spawnMachine(resolution, machineArgv, options = {}) {
   if (resolution.kind === 'binary') {
     return spawnSync(resolution.path, machineArgv, { stdio, env, encoding: 'utf8', maxBuffer });
   }
+
   if (resolution.kind === 'cargo') {
     return spawnSync(
       'cargo',
@@ -80,24 +94,16 @@ export function spawnMachine(resolution, machineArgv, options = {}) {
       { stdio, env, encoding: 'utf8', maxBuffer },
     );
   }
+
   const err = new Error(
-    `agentsam-machine binary not found. Tried: ${(resolution.tried || []).join(', ') || '(none)'}. Build with: cargo build --manifest-path native/agentsam-machine/Cargo.toml --release`,
+    'agentsam-machine is not installed. Run: agentsam machine install. ' +
+    'Standalone Cargo users can run: cargo install agentsam-machine-cli. ' +
+    'Tried: ' + ((resolution.tried || []).join(', ') || '(none)'),
   );
   err.code = 'AGENTSAM_MACHINE_BINARY_MISSING';
   throw err;
 }
 
-function which(cmd) {
-  const probe = process.platform === 'win32' ? ['where', [cmd]] : ['which', [cmd]];
-  const result = spawnSync(probe[0], probe[1], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-  if (result.status !== 0) return null;
-  const line = String(result.stdout || '')
-    .split(/\r?\n/)
-    .map((s) => s.trim())
-    .find(Boolean);
-  return line || null;
-}
-
 export function machineSdkRoot() {
   return sdkRoot;
 }