@awak-app/simy-cli 0.1.0 → 0.1.2

package/src/agent.js

@@ -1,11 +1,23 @@
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
+import { dirname, resolve } from "node:path";
 
 import {
+  applyLocalHumanDecision,
+  continueLocalCodingRun,
+  continueLocalCodingRunAfterRepositoryApproval,
   createRun,
   LocalRunRegistry,
+  isLocalRepositoryApprovalPending,
+  pauseLocalCodingRun,
+  queueLocalCodingGuidance,
   recheckLocalCodingRun,
+  publishRestoredLocalCodingRun,
+  resolveRepositoryPath,
+  restoreRun,
+  resumeLocalCodingRun,
   startLocalCodingRun,
+  stopLocalCodingRun,
   toCompatibleCodingLoopState,
   toLedgerSnapshot,
 } from "./runner.js";
@@ -16,19 +28,211 @@ import {
   sessionPath,
   writeSession,
 } from "./session-store.js";
+import { isRequestOriginAllowed, resolveWebOrigin } from "./web-origin.js";
+import {
+  cleanupExpiredRuns,
+  cleanupRunAttachments,
+  stageRunAttachments,
+  referenceLocalAttachmentPaths,
+} from "./local-attachments.js";
+import { discoverWorkspace } from "./workspace-context.js";
+import { resolveBackendExecutable } from "./backend-executable.js";
+import {
+  resolveWebApiBaseUrl,
+  sessionRequiresWebAuthorization,
+  webApiErrorMessage,
+  webApiHeaders,
+  webApiUrl,
+} from "./web-api.js";
+import {
+  defaultRepositoryScanRoot,
+  findRepository,
+  mergeRepositoryInventory,
+  readRepositoryInventory,
+  scanGitRepositories,
+  writeRepositoryInventory,
+} from "./repository-inventory.js";
 
-const DEFAULT_WEB_ORIGIN = "http://localhost:3000";
-const ALLOWED_ORIGIN_RE = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$|^https:\/\/app\.simy\.one$/;
+const DEVICE_HEARTBEAT_INTERVAL_MS = 20_000;
 
-export async function startAgent({ requestedPort = 0, daemon = false } = {}) {
-  const apiOrigin = process.env.SIMY_API_ORIGIN || DEFAULT_WEB_ORIGIN;
+export async function startAgent({
+  requestedPort = 0,
+  daemon = false,
+  webOrigin = null,
+  sessionRoot,
+  dependencies = {},
+  quiet = false,
+} = {}) {
+  const apiOrigin = resolveWebOrigin(webOrigin);
   const registry = new LocalRunRegistry();
   const authNonce = randomBytes(16).toString("base64url");
-  let session = await readSession();
+  let session = await readSession(apiOrigin, sessionRoot);
+  if (session && sessionRequiresWebAuthorization(session, apiOrigin)) session = null;
+  await cleanupExpiredRuns();
+  const workspace = dependencies.discoverWorkspace
+    ? await dependencies.discoverWorkspace()
+    : await discoverWorkspace(dependencies.cwd ?? process.cwd());
+  const persistedInventory = await readRepositoryInventory(sessionRoot);
+  let authorizedRepositoryRoots = [...persistedInventory.authorizedRoots];
+  let repositoryInventory = mergeRepositoryInventory(
+    persistedInventory.repositories,
+    workspace.repository
+      ? [
+          {
+            repository: workspace.repository,
+            branch: workspace.branch,
+            local_path: workspace.localPath,
+          },
+        ]
+      : [],
+  );
+  const availableCapabilities = await readCapabilities(dependencies);
+  const heartbeatDevice = dependencies.heartbeatDevice || heartbeatLocalDevice;
+  const runOptions = dependencies.runOptions || {};
+  const repositoryScanRoot = resolve(
+    String(
+      dependencies.repositoryScanRoot ||
+        process.env.SIMY_REPO_ROOT ||
+        (workspace.repository ? dirname(workspace.localPath) : workspace.localPath) ||
+        defaultRepositoryScanRoot(),
+    ),
+  );
+  let port = requestedPort;
+  let heartbeatTimer = null;
+  let heartbeatInFlight = null;
+
+  const restoreRemoteRuns = async () => {
+    if (!isSessionValid(session, Date.now(), apiOrigin) || !session?.device_id) return;
+    const snapshots = dependencies.listRemoteRuns
+      ? await dependencies.listRemoteRuns({
+          apiOrigin,
+          apiBaseUrl: session.api_base_url,
+          token: session.token,
+        })
+      : await listRemoteRuns({
+          apiOrigin,
+          apiBaseUrl: session.api_base_url,
+          token: session.token,
+        });
+    for (const snapshot of snapshots) {
+      if (!snapshot?.id || registry.has(snapshot.id)) continue;
+      const repository = findRepository(repositoryInventory, snapshot.charter?.repository);
+      const restoredRun = restoreRun({
+        snapshot,
+        session,
+        apiOrigin,
+        localPath: repository?.local_path || null,
+      });
+      registry.create(restoredRun);
+      await publishRestoredLocalCodingRun(restoredRun);
+    }
+  };
+
+  const heartbeat = () => {
+    if (!isSessionValid(session, Date.now(), apiOrigin)) return Promise.resolve(false);
+    if (heartbeatInFlight) return heartbeatInFlight;
+    heartbeatInFlight = heartbeatDevice({
+      apiOrigin,
+      apiBaseUrl: session.api_base_url,
+      token: session.token,
+      port,
+      capabilities: availableCapabilities,
+      repoInventory: repositoryInventory,
+    })
+      .then(() => true)
+      .finally(() => {
+        heartbeatInFlight = null;
+      });
+    return heartbeatInFlight;
+  };
+
+  const startHeartbeatTimer = () => {
+    if (heartbeatTimer) return;
+    heartbeatTimer = setInterval(() => {
+      void heartbeat().catch((error) => reportHeartbeatError(error, quiet));
+    }, DEVICE_HEARTBEAT_INTERVAL_MS);
+    heartbeatTimer.unref();
+  };
+
+  const synchronizeAuthorizedSession = async () => {
+    try {
+      await heartbeat();
+    } catch (error) {
+      reportHeartbeatError(error, quiet);
+    }
+    try {
+      await restoreRemoteRuns();
+    } catch (error) {
+      reportStartupConnectionError(error, quiet);
+    }
+  };
+
+  const scanRepositories = async (root) => {
+    const scan = dependencies.scanRepositories
+      ? await dependencies.scanRepositories(root)
+      : await scanGitRepositories(root);
+    repositoryInventory = mergeRepositoryInventory(repositoryInventory, scan.repositories);
+    authorizedRepositoryRoots = [
+      ...new Set([...authorizedRepositoryRoots, scan.root].filter(Boolean)),
+    ];
+    await writeRepositoryInventory(
+      {
+        authorizedRoots: authorizedRepositoryRoots,
+        repositories: repositoryInventory,
+        scannedAt: scan.scannedAt,
+      },
+      sessionRoot,
+    );
+    await heartbeat().catch((error) => reportHeartbeatError(error, quiet));
+    return {
+      ...scan,
+      discoveredRepositories: mergeRepositoryInventory(scan.repositories),
+      repositories: [...repositoryInventory],
+    };
+  };
+
+  const isRepositoryScanAuthorized = () =>
+    authorizedRepositoryRoots.some((item) => resolve(item) === repositoryScanRoot);
+
+  const refreshAuthorizedRepositoryInventory = async () => {
+    if (!isRepositoryScanAuthorized()) return null;
+    return scanRepositories(repositoryScanRoot);
+  };
+
+  const ensureRepositoryIndexed = async (repository) => {
+    const indexed = findRepository(repositoryInventory, repository);
+    if (indexed || !isRepositoryScanAuthorized()) return indexed;
+    await refreshAuthorizedRepositoryInventory();
+    return findRepository(repositoryInventory, repository);
+  };
+
+  const selectRepository = async (run, repository) => {
+    const selected = repository?.local_path
+      ? repositoryInventory.find(
+          (item) =>
+            item.local_path === repository.local_path &&
+            item.repository.toLowerCase() === repository.repository.toLowerCase(),
+        )
+      : findRepository(repositoryInventory, repository?.repository || repository);
+    if (!selected) throw new Error("Select a repository discovered by the authorized scan.");
+    if (run && selected.repository.toLowerCase() !== run.request.repository.toLowerCase()) {
+      throw new Error(`This run requires ${run.request.repository}; select that local repository.`);
+    }
+    if (!run) return selected;
+    return continueLocalCodingRunAfterRepositoryApproval(
+      run,
+      { repository: selected.repository, localPath: selected.local_path },
+      runOptions,
+    );
+  };
 
   const server = createServer(async (req, res) => {
     try {
-      applyCors(req, res);
+      if (!isRequestOriginAllowed(req.headers.origin, apiOrigin)) {
+        json(res, 403, { error: "request origin does not match the configured SIMY Web host" });
+        return;
+      }
+      applyCors(req, res, apiOrigin);
       if (req.method === "OPTIONS") {
         res.writeHead(204).end();
         return;
@@ -39,13 +243,43 @@ export async function startAgent({ requestedPort = 0, daemon = false } = {}) {
         json(res, 200, {
           ok: true,
           daemon,
-          session_valid: isSessionValid(session),
+          web_origin: apiOrigin,
+          session_valid: isSessionValid(session, Date.now(), apiOrigin),
           session_expires_at: session?.expires_at ?? null,
         });
         return;
       }
       if (req.method === "GET" && url.pathname === "/v1/capabilities") {
-        json(res, 200, await capabilities());
+        json(res, 200, await readCapabilities(dependencies));
+        return;
+      }
+      if (req.method === "POST" && url.pathname === "/v1/coding-loop/preflight") {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const body = await readJson(req);
+        const repository = String(body.repository || "").trim();
+        if (!repository) {
+          json(res, 400, { error: "repository is required" });
+          return;
+        }
+        if (body.backend !== "codex" && body.backend !== "claude") {
+          json(res, 400, { error: "backend must be codex or claude" });
+          return;
+        }
+        const backend = body.backend;
+        const indexedRepository = await ensureRepositoryIndexed(repository);
+        const environment = await inspectCodingLoopEnvironment({
+          repository,
+          backend,
+          localPath:
+            typeof body.local_path === "string"
+              ? body.local_path
+              : indexedRepository?.local_path || null,
+          dependencies,
+        });
+        json(res, 200, environment);
         return;
       }
       if (req.method === "POST" && url.pathname === "/v1/auth/complete") {
@@ -54,24 +288,43 @@ export async function startAgent({ requestedPort = 0, daemon = false } = {}) {
           json(res, 401, { error: "invalid nonce" });
           return;
         }
+        if (body.api_origin !== apiOrigin) {
+          json(res, 403, { error: "authorization origin does not match the configured host" });
+          return;
+        }
+        let apiBaseUrl;
+        try {
+          apiBaseUrl = resolveWebApiBaseUrl(apiOrigin, body.api_base_url);
+        } catch (error) {
+          json(res, 503, {
+            error: error instanceof Error ? error.message : "CLI API endpoint is unavailable",
+          });
+          return;
+        }
         session = {
           token: String(body.token || ""),
           device_id: typeof body.device_id === "string" ? body.device_id : null,
-          api_origin: typeof body.api_origin === "string" ? body.api_origin : apiOrigin,
+          api_origin: apiOrigin,
+          api_base_url: apiBaseUrl,
           expires_at: typeof body.expires_at === "string" ? body.expires_at : expiresAtFromNow(),
         };
-        await writeSession(session);
+        await writeSession(apiOrigin, session, sessionRoot);
+        startHeartbeatTimer();
+        loginUrl = null;
+        registry.emit("change", registry.list());
         json(res, 200, { ok: true, expires_at: session.expires_at });
+        void synchronizeAuthorizedSession();
         return;
       }
       if (req.method === "POST" && url.pathname === "/v1/coding-loop/start") {
-        if (!isSessionValid(session)) {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
           return;
         }
-        const body = await readJson(req);
+        const { body, attachments } = await readCodingLoopStart(req);
         const verified = await verifyLaunchChallenge({
-          apiOrigin: session.api_origin || apiOrigin,
+          apiOrigin,
+          apiBaseUrl: session.api_base_url,
           token: session.token,
           runId: String(body.run_id || ""),
           challenge: String(body.challenge || ""),
@@ -89,6 +342,18 @@ export async function startAgent({ requestedPort = 0, daemon = false } = {}) {
           json(res, 409, { error: "coding loop run already exists" });
           return;
         }
+        let stagedAttachments = [];
+        try {
+          stagedAttachments = await stageRunAttachments({
+            runId,
+            attachments,
+            manifest: attachments.length > 0 ? body.attachment_manifest ?? [] : undefined,
+          });
+        } catch (error) {
+          json(res, 400, { error: error instanceof Error ? error.message : "attachment rejected" });
+          return;
+        }
+        const indexedRepository = await ensureRepositoryIndexed(body.repository);
         const run = createRun({
           runId,
           request: {
@@ -99,7 +364,10 @@ export async function startAgent({ requestedPort = 0, daemon = false } = {}) {
                 : null,
             requirement: String(body.requirement || ""),
             repository: String(body.repository || ""),
-            local_path: typeof body.local_path === "string" ? body.local_path : null,
+            local_path:
+              typeof body.local_path === "string"
+                ? body.local_path
+                : indexedRepository?.local_path || null,
             base_branch: typeof body.base_branch === "string" ? body.base_branch : "dev",
             max_attempts: body.max_attempts,
             ui_evidence_root:
@@ -123,16 +391,167 @@ export async function startAgent({ requestedPort = 0, daemon = false } = {}) {
               typeof body.design_review_url === "string" ? body.design_review_url : "",
             must_not: Array.isArray(body.must_not) ? body.must_not : [],
             proposal_id: typeof body.proposal_id === "string" ? body.proposal_id : null,
+            attachments: stagedAttachments,
           },
           session,
-          apiOrigin: session.api_origin || apiOrigin,
+          apiOrigin,
         });
-        registry.create(run);
-        void startLocalCodingRun(run);
+        try {
+          registry.create(run);
+        } catch (error) {
+          await cleanupRunAttachments(stagedAttachments);
+          throw error;
+        }
+        void startLocalCodingRun(run, dependencies.runOptions);
         json(res, 202, { ok: true, run_id: run.id });
         return;
       }
 
+      const controlMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/control$/);
+      if (req.method === "POST" && controlMatch) {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const run = registry.get(decodeURIComponent(controlMatch[1]));
+        if (!run) {
+          json(res, 404, { error: "run not found" });
+          return;
+        }
+        const body = await readJson(req);
+        if (body.action === "stop") {
+          await stopLocalCodingRun(run);
+        } else if (body.action === "pause") {
+          pauseLocalCodingRun(run);
+        } else if (body.action === "resume") {
+          resumeLocalCodingRun(run);
+        } else {
+          json(res, 400, { error: "action must be pause, resume, or stop" });
+          return;
+        }
+        json(res, 200, {
+          ok: true,
+          run_id: run.id,
+          action: body.action,
+          state: run.status,
+          control_state: run.controlState,
+          delivery_status: "delivered",
+        });
+        return;
+      }
+
+      const guidanceMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/guidance$/);
+      if (req.method === "POST" && guidanceMatch) {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const run = registry.get(decodeURIComponent(guidanceMatch[1]));
+        if (!run) {
+          json(res, 404, { error: "run not found" });
+          return;
+        }
+        const body = await readJson(req);
+        const message = String(body.message || "").trim();
+        if (!message) {
+          json(res, 400, { error: "message is required" });
+          return;
+        }
+        if (!run.operation && !run.child) {
+          json(res, 409, { error: "run is not actively executing" });
+          return;
+        }
+        queueLocalCodingGuidance(run, message);
+        json(res, 202, {
+          ok: true,
+          run_id: run.id,
+          delivery_status: "queued",
+        });
+        return;
+      }
+
+      const hilMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/hil$/);
+      if (hilMatch) {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const run = registry.get(decodeURIComponent(hilMatch[1]));
+        if (!run) {
+          json(res, 404, { error: "run not found" });
+          return;
+        }
+        if (!isLocalRepositoryApprovalPending(run)) {
+          json(res, 409, { error: "run is not waiting for local repository approval" });
+          return;
+        }
+
+        if (req.method === "GET") {
+          json(res, 200, {
+            request: localRepositoryHilRequest(
+              run,
+              repositoryScanRoot,
+              authorizedRepositoryRoots,
+            ),
+          });
+          return;
+        }
+
+        if (req.method === "POST") {
+          const body = await readJson(req);
+          const requestId = localRepositoryHilRequestId(run);
+          if (body.request_id !== requestId) {
+            json(res, 409, { error: "HIL request is stale or does not match this run" });
+            return;
+          }
+          if (body.decision === "reject") {
+            json(res, 200, {
+              ok: true,
+              request_id: requestId,
+              decision: "rejected",
+              state: "waiting_human",
+            });
+            return;
+          }
+          if (body.decision !== "approve") {
+            json(res, 400, { error: "decision must be approve or reject" });
+            return;
+          }
+
+          const scan = await scanRepositories(repositoryScanRoot);
+          const selected = findRepository(scan.discoveredRepositories, run.request.repository);
+          if (!selected) {
+            json(res, 404, {
+              error: `${run.request.repository} was not found under ${scan.root}`,
+              code: "repository_not_found_in_scan",
+              root: scan.root,
+              repository: run.request.repository,
+              discovered_count: scan.discoveredRepositories.length,
+              truncated: scan.truncated,
+            });
+            return;
+          }
+
+          const continuation = continueLocalCodingRunAfterRepositoryApproval(
+            run,
+            { repository: selected.repository, localPath: selected.local_path },
+            runOptions,
+          );
+          json(res, 202, {
+            ok: true,
+            request_id: requestId,
+            decision: "approved",
+            run_id: run.id,
+            repository: selected.repository,
+            local_path: selected.local_path,
+            root: scan.root,
+            state: "starting",
+          });
+          void continuation.catch((error) => reportRepositoryResumeError(error, quiet));
+          return;
+        }
+      }
+
       const recheckMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/recheck$/);
       if (req.method === "POST" && recheckMatch) {
         const run = registry.get(decodeURIComponent(recheckMatch[1]));
@@ -163,62 +582,305 @@ export async function startAgent({ requestedPort = 0, daemon = false } = {}) {
 
   await new Promise((resolve) => server.listen(requestedPort, "127.0.0.1", resolve));
   const address = server.address();
-  const port = typeof address === "object" && address ? address.port : requestedPort;
-  console.log(`SIMY local agent listening on http://127.0.0.1:${port}`);
+  port = typeof address === "object" && address ? address.port : requestedPort;
+  if (!quiet) {
+    console.log(`SIMY local agent listening on http://127.0.0.1:${port}`);
+    console.log(`SIMY Web host: ${apiOrigin}`);
+  }
 
-  if (!isSessionValid(session)) {
-    const loginUrl = new URL("/local-cli/connect", apiOrigin);
+  let loginUrl = null;
+  if (!isSessionValid(session, Date.now(), apiOrigin)) {
+    loginUrl = new URL("/local-cli/connect", apiOrigin);
     loginUrl.searchParams.set("port", String(port));
     loginUrl.searchParams.set("nonce", authNonce);
-    console.log(`Sign in to SIMY: ${loginUrl.toString()}`);
-    console.log(`Session file: ${sessionPath()}`);
+    if (!quiet) {
+      console.log(`Sign in to SIMY: ${loginUrl.toString()}`);
+      console.log(`Session file: ${sessionPath(apiOrigin, sessionRoot)}`);
+    }
   }
 
-  return { server, port };
+  if (isSessionValid(session, Date.now(), apiOrigin)) {
+    try {
+      await refreshAuthorizedRepositoryInventory();
+      await heartbeat();
+      await restoreRemoteRuns();
+    } catch (error) {
+      reportStartupConnectionError(error, quiet);
+    }
+    startHeartbeatTimer();
+  }
+
+  server.on("close", () => {
+    if (heartbeatTimer) clearInterval(heartbeatTimer);
+    registry.close();
+  });
+  return {
+    server,
+    port,
+    registry,
+    webOrigin: apiOrigin,
+    get loginUrl() {
+      return loginUrl?.toString() ?? null;
+    },
+    workspace,
+    repositoryScanRoot,
+    capabilities: availableCapabilities,
+    controls: {
+      repositoryInventory: () => [...repositoryInventory],
+      scanRepositories,
+      selectRepository,
+      create: async (input) => {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          throw new Error("Sign in to SIMY before starting a coding task.");
+        }
+        const requirement = String(input.requirement || "").trim();
+        const repository = String(input.repository || "").trim();
+        const backend = input.backend === "claude" ? "claude" : "codex";
+        if (!requirement) throw new Error("Describe the coding task first.");
+        if (!repository) throw new Error("Set a repository with /repo owner/name.");
+        if (availableCapabilities?.backends?.[backend] !== true) {
+          throw new Error(`${backend === "claude" ? "Claude Code" : "Codex"} is not available on PATH.`);
+        }
+        const indexedRepository = await ensureRepositoryIndexed(repository);
+        const request = {
+          requirement,
+          repository,
+          local_path: indexedRepository?.local_path || input.localPath || workspace.localPath,
+          base_branch: String(input.baseBranch || "dev"),
+          backend,
+          max_attempts: 3,
+          acceptance_criteria: [],
+          expected_tests: [],
+          expected_evidence: [],
+          required_checks: [],
+          require_human_approval: true,
+          must_not: [],
+          attachments: await referenceLocalAttachmentPaths(input.attachmentPaths || []),
+        };
+        await resolveRepositoryPath(request);
+        const remoteRun = dependencies.createRemoteRun
+          ? await dependencies.createRemoteRun(request)
+          : await createRemoteRun({
+              apiOrigin,
+              apiBaseUrl: session.api_base_url,
+              token: session.token,
+              request,
+            });
+        const runId = String(remoteRun?.id || "");
+        if (!runId) throw new Error("SIMY Web did not return a coding run id.");
+        const run = createRun({ runId, request, session, apiOrigin });
+        registry.create(run);
+        void startLocalCodingRun(run, runOptions);
+        return run;
+      },
+      continue: (run, guidance) => continueLocalCodingRun(run, guidance, runOptions),
+      applyDecision: (run, decision) => applyLocalHumanDecision(run, decision, runOptions),
+      queueGuidance: queueLocalCodingGuidance,
+      pause: pauseLocalCodingRun,
+      resume: resumeLocalCodingRun,
+      stop: stopLocalCodingRun,
+      recheck: (run) =>
+        recheckLocalCodingRun(run, { collectEvidence: runOptions.collectEvidence }),
+    },
+  };
+}
+
+async function createRemoteRun({ apiOrigin, apiBaseUrl, token, request }) {
+  const response = await fetch(webApiUrl("runs", { webOrigin: apiOrigin, apiBaseUrl }), {
+    method: "POST",
+    headers: webApiHeaders(
+      { token },
+      { "Content-Type": "application/json" },
+    ),
+    body: JSON.stringify({
+      requirement: request.requirement,
+      repository: request.repository,
+      backend: request.backend,
+      base_branch: request.base_branch,
+      max_attempts: request.max_attempts,
+      acceptance_criteria: request.acceptance_criteria,
+      expected_tests: request.expected_tests,
+      expected_evidence: request.expected_evidence,
+      must_not: request.must_not,
+    }),
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw new Error(webApiErrorMessage(payload, response.status));
+  }
+  return payload?.run;
+}
+
+async function listRemoteRuns({ apiOrigin, apiBaseUrl, token }) {
+  const response = await fetch(webApiUrl("runs", { webOrigin: apiOrigin, apiBaseUrl }), {
+    method: "GET",
+    headers: webApiHeaders({ token }),
+    signal: AbortSignal.timeout(5_000),
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw new Error(webApiErrorMessage(payload, response.status));
+  }
+  return Array.isArray(payload?.runs) ? payload.runs : [];
+}
+
+export async function heartbeatLocalDevice({
+  apiOrigin,
+  apiBaseUrl,
+  token,
+  port,
+  capabilities,
+  repoInventory,
+}) {
+  const response = await fetch(
+    webApiUrl("devices/heartbeat", { webOrigin: apiOrigin, apiBaseUrl }),
+    {
+      method: "POST",
+      headers: webApiHeaders(
+        { token },
+        { "Content-Type": "application/json" },
+      ),
+      body: JSON.stringify({
+        port,
+        capabilities,
+        repo_inventory: repoInventory,
+      }),
+      signal: AbortSignal.timeout(5_000),
+    },
+  );
+  if (!response.ok) {
+    const payload = await response.json().catch(() => null);
+    throw new Error(webApiErrorMessage(payload, response.status));
+  }
+}
+
+function reportHeartbeatError(error, quiet) {
+  if (quiet) return;
+  console.error(
+    `SIMY device heartbeat failed: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+
+function reportStartupConnectionError(error, quiet) {
+  if (quiet) return;
+  console.error(
+    `SIMY startup synchronization failed: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+
+function reportRepositoryResumeError(error, quiet) {
+  if (quiet) return;
+  console.error(
+    `SIMY repository-approved run failed to resume: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+
+function localRepositoryHilRequestId(run) {
+  return `local-repository-scan:${run.id}`;
+}
+
+function localRepositoryHilRequest(run, root, authorizedRoots) {
+  return {
+    id: localRepositoryHilRequestId(run),
+    kind: "local_repository_scan",
+    status: "pending",
+    title: "Allow SIMY CLI to find the local repository",
+    description: `Scan ${root} for the ${run.request.repository} Git checkout, then continue this run.`,
+    details: {
+      repository: run.request.repository,
+      root,
+      previously_authorized: authorizedRoots.some((item) => resolve(item) === root),
+      reads: ["directory names", "Git origin remotes", "current Git branches"],
+      excludes: [
+        "source file contents",
+        "hidden directories",
+        "dependency directories",
+        "cache directories",
+        "symbolic links",
+      ],
+    },
+    actions: [
+      { id: "approve", label: "Allow scan", tone: "primary" },
+      { id: "reject", label: "Not now", tone: "secondary" },
+    ],
+  };
 }
 
 async function capabilities() {
-  const [codex, claude] = await Promise.all([commandAvailable("codex"), commandAvailable("claude")]);
+  const [codex, claude] = await Promise.all([
+    resolveBackendExecutable("codex"),
+    resolveBackendExecutable("claude"),
+  ]);
   return {
-    backends: { codex, claude },
+    backends: { codex: Boolean(codex), claude: Boolean(claude) },
+    features: { repository_scan_approval: true },
     session_ttl_hours: 48,
   };
 }
 
-async function commandAvailable(command) {
-  const { spawn } = await import("node:child_process");
-  return new Promise((resolve) => {
-    let settled = false;
-    let timeout;
-    const child = spawn(command, ["--version"], { stdio: "ignore" });
-    const finish = (available) => {
-      if (settled) return;
-      settled = true;
-      if (timeout) clearTimeout(timeout);
-      resolve(available);
-    };
-    timeout = setTimeout(() => {
-      child.kill("SIGTERM");
-      finish(false);
-    }, 1500);
-    child.on("error", () => finish(false));
-    child.on("close", (code) => finish(code === 0));
+async function readCapabilities(dependencies) {
+  return dependencies.capabilities ? dependencies.capabilities() : capabilities();
+}
+
+async function inspectCodingLoopEnvironment({ repository, backend, localPath, dependencies }) {
+  const checks = [
+    {
+      key: "session",
+      status: "passed",
+      summary: "Local CLI session is connected to this SIMY Web origin.",
+    },
+  ];
+  let repositoryPath = null;
+  try {
+    repositoryPath = await resolveRepositoryPath({ repository, local_path: localPath });
+    checks.push({
+      key: "repository",
+      status: "passed",
+      summary: `Verified ${repository} against the local Git origin.`,
+    });
+  } catch (error) {
+    checks.push({
+      key: "repository",
+      status: "failed",
+      summary: error instanceof Error ? error.message : "Local repository could not be resolved.",
+    });
+  }
+
+  const available = await readCapabilities(dependencies);
+  const backendAvailable = available?.backends?.[backend] === true;
+  checks.push({
+    key: "backend",
+    status: backendAvailable ? "passed" : "failed",
+    summary: backendAvailable
+      ? `${backend === "claude" ? "Claude Code" : "Codex"} is available locally.`
+      : `${backend === "claude" ? "Claude Code" : "Codex"} is not available on PATH.`,
   });
+
+  return {
+    ready: Boolean(repositoryPath && backendAvailable),
+    repository,
+    backend,
+    local_path: repositoryPath,
+    checks,
+  };
 }
 
-async function verifyLaunchChallenge({ apiOrigin, token, runId, challenge }) {
+async function verifyLaunchChallenge({ apiOrigin, apiBaseUrl, token, runId, challenge }) {
   try {
-    const response = await fetch(new URL("/api/local-cli/challenges/verify", apiOrigin), {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/json",
+    const response = await fetch(
+      webApiUrl("challenges/verify", { webOrigin: apiOrigin, apiBaseUrl }),
+      {
+        method: "POST",
+        headers: webApiHeaders(
+          { token },
+          { "Content-Type": "application/json" },
+        ),
+        body: JSON.stringify({ run_id: runId, challenge }),
       },
-      body: JSON.stringify({ run_id: runId, challenge }),
-    });
+    );
     if (response.ok) return { ok: true };
     const payload = await response.json().catch(() => null);
-    return { ok: false, error: payload?.error ? String(payload.error) : `HTTP ${response.status}` };
+    return { ok: false, error: webApiErrorMessage(payload, response.status) };
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : "challenge check failed" };
   }
@@ -248,11 +910,14 @@ function streamRun(res, run) {
   res.on("close", () => run.emitter.off("event", listener));
 }
 
-function applyCors(req, res) {
+function applyCors(req, res, webOrigin) {
   const origin = req.headers.origin;
-  if (origin && ALLOWED_ORIGIN_RE.test(origin)) {
-    res.setHeader("Access-Control-Allow-Origin", origin);
+  if (origin === webOrigin) {
+    res.setHeader("Access-Control-Allow-Origin", webOrigin);
     res.setHeader("Vary", "Origin");
+    if (req.headers["access-control-request-private-network"] === "true") {
+      res.setHeader("Access-Control-Allow-Private-Network", "true");
+    }
   }
   res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
   res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
@@ -268,3 +933,26 @@ async function readJson(req) {
   for await (const chunk of req) raw += chunk;
   return raw ? JSON.parse(raw) : {};
 }
+
+async function readCodingLoopStart(req) {
+  const contentType = String(req.headers["content-type"] || "");
+  if (!contentType.toLowerCase().startsWith("multipart/form-data")) {
+    return { body: await readJson(req), attachments: [] };
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > 52 * 1024 * 1024) throw new Error("attachment request exceeds the 52 MB limit");
+    chunks.push(Buffer.from(chunk));
+  }
+  const form = await new Response(Buffer.concat(chunks), {
+    headers: { "Content-Type": contentType },
+  }).formData();
+  const payload = form.get("payload");
+  if (typeof payload !== "string") throw new Error("multipart payload field is required");
+  const attachments = form
+    .getAll("attachments")
+    .filter((value) => value && typeof value === "object" && typeof value.arrayBuffer === "function");
+  return { body: JSON.parse(payload), attachments };
+}