impel-cli 0.20.2 → 0.20.4

package/src/remote/checkpoint.js

@@ -0,0 +1,248 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+import { isSessionsUUID } from "./broker.js";
+
+const PROVIDERS = new Set(["codex", "claude"]);
+const MODES = new Set(["fork", "resume"]);
+const SURFACES = new Set(["desktop", "cli", "app_server", "runner"]);
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;
+const SHA_RE = /^[a-f0-9]{64}$/u;
+const DENIED_PATH_RE = /(?:^|\/)(?:auth|credential|credentials|token|tokens|keychain|config)(?:\.|\/|$)/iu;
+const MAX_FILES = 20_000;
+const MAX_FILE_BYTES = 128 << 20;
+const MAX_TOTAL_BYTES = 512 << 20;
+const MANIFEST_KEYS = new Set([
+  "schemaVersion", "itemCount", "provider", "providerVersion", "sourceSurface", "destinationSurface",
+  "mode", "runId", "providerSessionId", "providerThreadId", "impelSessionId", "quiescence", "files",
+  "createdAt", "closedAt", "rootManifestHash",
+]);
+
+function exactKeys(value, allowed) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).every((key) => allowed.has(key));
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function sha256File(filePath) {
+  return sha256(fs.readFileSync(filePath));
+}
+
+function canonicalManifestCore(manifest, runId = manifest.runId) {
+  return {
+    schemaVersion: manifest.schemaVersion,
+    itemCount: manifest.itemCount,
+    provider: manifest.provider,
+    providerVersion: manifest.providerVersion,
+    sourceSurface: manifest.sourceSurface,
+    destinationSurface: manifest.destinationSurface,
+    mode: manifest.mode,
+    runId,
+    providerSessionId: manifest.providerSessionId,
+    ...(manifest.providerThreadId ? { providerThreadId: manifest.providerThreadId } : {}),
+    impelSessionId: manifest.impelSessionId,
+    quiescence: {
+      proven: manifest.quiescence?.proven,
+      mechanism: manifest.quiescence?.mechanism,
+    },
+    files: Array.isArray(manifest.files) ? manifest.files.map((file) => ({
+      path: file.path,
+      length: file.length,
+      sha256: file.sha256,
+    })) : manifest.files,
+    createdAt: manifest.createdAt,
+    closedAt: manifest.closedAt,
+  };
+}
+
+function safePath(value) {
+  const relative = String(value || "").replaceAll("\\", "/");
+  if (!relative || relative.startsWith("/") || relative.includes("\0")
+    || relative.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new Error("provider checkpoint manifest contains an unsafe path");
+  }
+  if (DENIED_PATH_RE.test(relative)) throw new Error(`provider checkpoint contains denied credential/config path ${relative}`);
+  return relative;
+}
+
+function octal(buffer) {
+  const text = buffer.toString("ascii").replace(/\0.*$/u, "").trim();
+  return text ? Number.parseInt(text, 8) : 0;
+}
+
+function inspectTar(archivePath) {
+  const stat = fs.statSync(archivePath);
+  if (!stat.isFile() || stat.size < 1 || stat.size > MAX_TOTAL_BYTES) {
+    throw new Error("provider checkpoint archive exceeds configured limits");
+  }
+  const archive = fs.readFileSync(archivePath);
+  const entries = [];
+  let totalBytes = 0;
+  let offset = 0;
+  while (offset + 512 <= archive.length) {
+    const header = archive.subarray(offset, offset + 512);
+    offset += 512;
+    if (header.every((byte) => byte === 0)) break;
+    const name = header.subarray(0, 100).toString("utf8").replace(/\0.*$/u, "");
+    const prefix = header.subarray(345, 500).toString("utf8").replace(/\0.*$/u, "");
+    const relative = safePath(prefix ? `${prefix}/${name}` : name);
+    const type = header[156];
+    if (type !== 0 && type !== 0x30) throw new Error(`provider checkpoint contains unsupported link or special entry ${relative}`);
+    const length = octal(header.subarray(124, 136));
+    if (!Number.isSafeInteger(length) || length < 0) {
+      throw new Error("provider checkpoint archive contains an invalid length");
+    }
+    totalBytes += length;
+    if (entries.length >= MAX_FILES + 1 || length > MAX_FILE_BYTES || totalBytes > MAX_TOTAL_BYTES) {
+      throw new Error("provider checkpoint archive exceeds configured limits");
+    }
+    if (offset + length > archive.length) {
+      throw new Error("provider checkpoint archive is truncated");
+    }
+    const contents = archive.subarray(offset, offset + length);
+    entries.push({ path: relative, length, sha256: sha256(contents), contents: Buffer.from(contents), mode: octal(header.subarray(100, 108)) });
+    offset += Math.ceil(length / 512) * 512;
+  }
+  return entries;
+}
+
+function writeField(header, offset, length, value) {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(String(value), "utf8");
+  if (bytes.length > length) throw new Error("provider checkpoint tar header overflow");
+  bytes.copy(header, offset);
+}
+
+function writeOctal(header, offset, length, value) {
+  writeField(header, offset, length, `${Math.max(0, value).toString(8).padStart(length - 1, "0")}\0`);
+}
+
+function tarFields(relative) {
+  const normalized = safePath(relative);
+  const bytes = Buffer.from(normalized, "utf8");
+  if (bytes.length <= 100) return { name: bytes, prefix: Buffer.alloc(0) };
+  const parts = normalized.split("/");
+  for (let index = parts.length - 1; index > 0; index -= 1) {
+    const prefix = Buffer.from(parts.slice(0, index).join("/"), "utf8");
+    const name = Buffer.from(parts.slice(index).join("/"), "utf8");
+    if (prefix.length <= 155 && name.length <= 100) return { name, prefix };
+  }
+  throw new Error(`provider checkpoint path is too long: ${relative}`);
+}
+
+function tarHeader(relative, length, mode = 0o600) {
+  const header = Buffer.alloc(512);
+  const fields = tarFields(relative);
+  writeField(header, 0, 100, fields.name);
+  writeOctal(header, 100, 8, mode & 0o777);
+  writeOctal(header, 108, 8, 0);
+  writeOctal(header, 116, 8, 0);
+  writeOctal(header, 124, 12, length);
+  writeOctal(header, 136, 12, 0);
+  header.fill(0x20, 148, 156);
+  writeField(header, 156, 1, "0");
+  writeField(header, 257, 6, "ustar\0");
+  writeField(header, 263, 2, "00");
+  writeField(header, 345, 155, fields.prefix);
+  const checksum = header.reduce((sum, byte) => sum + byte, 0);
+  writeField(header, 148, 8, `${checksum.toString(8).padStart(6, "0")}\0 `);
+  return header;
+}
+
+function writeTar(target, entries) {
+  const descriptor = fs.openSync(target, "w", 0o600);
+  try {
+    for (const entry of entries) {
+      fs.writeSync(descriptor, tarHeader(entry.path, entry.contents.length, entry.mode));
+      fs.writeSync(descriptor, entry.contents);
+      const remainder = entry.contents.length % 512;
+      if (remainder) fs.writeSync(descriptor, Buffer.alloc(512 - remainder));
+    }
+    fs.writeSync(descriptor, Buffer.alloc(1024));
+  } finally { fs.closeSync(descriptor); }
+}
+
+export function prepareProviderCheckpoint({ archivePath, manifestPath, outputPath, provider, mode, runId, sessionId }) {
+  const raw = fs.readFileSync(manifestPath, "utf8");
+  let manifest;
+  try { manifest = JSON.parse(raw); } catch { throw new Error("provider checkpoint manifest is not valid JSON"); }
+  if (
+    !exactKeys(manifest, MANIFEST_KEYS)
+    || manifest?.schemaVersion !== 1
+    || manifest.itemCount !== 1
+    || manifest.provider !== provider
+    || !PROVIDERS.has(manifest.provider)
+    || typeof manifest.providerVersion !== "string" || !manifest.providerVersion.trim()
+    || !SURFACES.has(manifest.sourceSurface)
+    || !SURFACES.has(manifest.destinationSurface)
+    || manifest.mode !== mode || !MODES.has(manifest.mode)
+    || (manifest.runId !== undefined && manifest.runId !== null && manifest.runId !== runId)
+    || !ID_RE.test(String(manifest.providerSessionId || ""))
+    || (manifest.providerThreadId !== undefined && !ID_RE.test(String(manifest.providerThreadId || "")))
+    || !isSessionsUUID(sessionId)
+    || manifest.impelSessionId !== sessionId
+    || typeof manifest.createdAt !== "string" || !Number.isFinite(Date.parse(manifest.createdAt))
+    || typeof manifest.closedAt !== "string" || !Number.isFinite(Date.parse(manifest.closedAt))
+    || Date.parse(manifest.closedAt) < Date.parse(manifest.createdAt)
+    || !exactKeys(manifest.quiescence, new Set(["proven", "mechanism"]))
+    || manifest.quiescence?.proven !== true
+    || !new Set(["provider_snapshot", "stopped_and_flushed", "fork_operation"]).has(manifest.quiescence?.mechanism)
+    || !Array.isArray(manifest.files) || manifest.files.length > MAX_FILES
+    || !SHA_RE.test(String(manifest.rootManifestHash || ""))
+  ) throw new Error("provider checkpoint is not a closed, versioned, quiesced exact checkpoint for this run");
+  const core = canonicalManifestCore(manifest);
+  if (sha256(Buffer.from(JSON.stringify(core), "utf8")) !== manifest.rootManifestHash) {
+    throw new Error("provider checkpoint root manifest hash mismatch");
+  }
+  const declared = manifest.files.map((file) => ({
+    path: safePath(file?.path),
+    length: file?.length,
+    sha256: file?.sha256,
+  }));
+  if (
+    manifest.files.some((file) => !exactKeys(file, new Set(["path", "length", "sha256"])))
+    || declared.some((file) => !Number.isSafeInteger(file.length) || file.length < 0 || file.length > MAX_FILE_BYTES || !SHA_RE.test(String(file.sha256 || "")))
+    || declared.reduce((total, file) => total + file.length, 0) > MAX_TOTAL_BYTES
+  ) {
+    throw new Error("provider checkpoint manifest contains invalid file metadata");
+  }
+  const archiveEntries = inspectTar(archivePath);
+  const embeddedManifest = archiveEntries.find((entry) => entry.path === "manifest.json");
+  if (embeddedManifest && embeddedManifest.contents.toString("utf8").trim() !== raw.trim()) {
+    throw new Error("provider checkpoint embedded manifest does not match the capture manifest");
+  }
+  const providerEntries = archiveEntries.filter((entry) => entry.path !== "manifest.json");
+  const actual = providerEntries.map(({ path: entryPath, length, sha256: entrySha }) => ({
+    path: entryPath, length, sha256: entrySha,
+  }));
+  if (JSON.stringify(actual) !== JSON.stringify(declared)) {
+    throw new Error("provider checkpoint archive does not match its manifest");
+  }
+  // Bind only the canonical manifest after the broker has assigned the run.
+  // Provider-native bytes are copied unchanged and rehashed above immediately
+  // before packing.
+  const boundCore = canonicalManifestCore(manifest, runId);
+  const boundManifestHash = sha256(Buffer.from(JSON.stringify(boundCore), "utf8"));
+  const boundManifest = { ...boundCore, rootManifestHash: boundManifestHash };
+  const boundManifestBytes = Buffer.from(`${JSON.stringify(boundManifest, null, 2)}\n`, "utf8");
+  writeTar(outputPath, [
+    { path: "manifest.json", contents: boundManifestBytes, mode: 0o600 },
+    ...providerEntries.map((entry) => ({ path: entry.path, contents: entry.contents, mode: entry.mode })),
+  ]);
+  const stat = fs.statSync(outputPath);
+  return {
+    path: outputPath,
+    length: stat.size,
+    sha256: sha256File(outputPath),
+    manifestHash: boundManifestHash,
+    manifest: boundManifest,
+  };
+}
+
+export const validateProviderCheckpoint = prepareProviderCheckpoint;
+
+export function exactCheckpointRequiredMessage(provider) {
+  return `${provider} fork requires a closed, version-matched provider checkpoint produced by a supported snapshot/fork operation; this CLI will not treat mirrored open provider files as exact. Rerun with --mode portable for an explicit non-exact transfer.`;
+}

package/src/remote/contracts.js

@@ -0,0 +1,89 @@
+export const REMOTE_CAPABILITY_SCHEMA_VERSION = 1;
+export const REMOTE_MODES = Object.freeze(["native", "fork", "portable"]);
+export const REMOTE_PROVIDERS = Object.freeze(["codex", "claude"]);
+export const REMOTE_SOURCE_SURFACES = Object.freeze(["desktop", "cli", "app_server"]);
+
+const MODE_SET = new Set(REMOTE_MODES);
+const PROVIDER_SET = new Set(REMOTE_PROVIDERS);
+const SURFACE_SET = new Set(REMOTE_SOURCE_SURFACES);
+const REASON_CODE_RE = /^[A-Z][A-Z0-9_]{0,127}$/u;
+
+export function normalizeRemoteMode(value) {
+  const mode = String(value || "").trim().toLowerCase();
+  if (!MODE_SET.has(mode)) {
+    throw new Error("--mode must be native, fork, or portable");
+  }
+  return mode;
+}
+
+export function normalizeRemoteProvider(value) {
+  const provider = String(value || "").trim().toLowerCase();
+  if (!PROVIDER_SET.has(provider)) throw new Error("--provider must be codex or claude");
+  return provider;
+}
+
+export function normalizeSourceSurface(value) {
+  const surface = String(value || "").trim().toLowerCase().replaceAll("-", "_");
+  if (!SURFACE_SET.has(surface)) throw new Error("--source must be desktop, cli, or app-server");
+  return surface;
+}
+
+export function assertRemoteCommandContract({ action, provider, mode, sourceSurface }) {
+  const normalizedProvider = normalizeRemoteProvider(provider);
+  const normalizedMode = normalizeRemoteMode(mode);
+  const normalizedSurface = normalizeSourceSurface(sourceSurface);
+  if (action === "handoff" && normalizedMode !== "native") {
+    throw new Error("handoff requires --mode native; use `impel remote dispatch` for fork or portable");
+  }
+  if (action === "dispatch" && !new Set(["fork", "portable"]).has(normalizedMode)) {
+    throw new Error("dispatch requires --mode fork or --mode portable; use `impel remote handoff` for native");
+  }
+  if (normalizedMode === "native" && normalizedProvider === "claude") {
+    throw new Error("Claude through the Impel gateway does not support native handoff; use --mode fork or --mode portable");
+  }
+  if (normalizedMode === "native" && normalizedSurface === "app_server") {
+    throw new Error("Codex App Server does not support Desktop native handoff; use --mode fork or --mode portable");
+  }
+  return {
+    action,
+    provider: normalizedProvider,
+    mode: normalizedMode,
+    sourceSurface: normalizedSurface,
+  };
+}
+
+export function normalizeCapabilityResponse(value, expected) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("broker returned an invalid remote capability response");
+  }
+  const alternatives = value.alternatives;
+  if (
+    value.schemaVersion !== REMOTE_CAPABILITY_SCHEMA_VERSION
+    || value.provider !== expected.provider
+    || value.sourceSurface !== expected.sourceSurface
+    || value.requestedMode !== expected.mode
+    || typeof value.supported !== "boolean"
+    || !Array.isArray(alternatives)
+    || alternatives.some((mode) => !MODE_SET.has(mode))
+    || (value.reasonCode !== null && value.reasonCode !== undefined
+      && (typeof value.reasonCode !== "string" || !REASON_CODE_RE.test(value.reasonCode)))
+  ) {
+    throw new Error("broker returned a mismatched or unsupported remote capability contract");
+  }
+  return Object.freeze({
+    schemaVersion: REMOTE_CAPABILITY_SCHEMA_VERSION,
+    provider: value.provider,
+    sourceSurface: value.sourceSurface,
+    requestedMode: value.requestedMode,
+    supported: value.supported,
+    alternatives: Object.freeze([...new Set(alternatives)]),
+    reasonCode: value.reasonCode || null,
+  });
+}
+
+export function capabilityFailureMessage(capability) {
+  const alternatives = capability.alternatives.length
+    ? ` Available explicit alternatives: ${capability.alternatives.join(", ")}.`
+    : "";
+  return `The broker does not support ${capability.provider} ${capability.requestedMode} from ${capability.sourceSurface} (${capability.reasonCode || "CAPABILITY_NOT_ENABLED"}).${alternatives}`;
+}

package/src/remote/state.js

@@ -12,7 +12,7 @@ export const REMOTE_ROOT = process.env.IMPEL_REMOTE_STATE_DIR || path.join(CONFI
 export const REMOTE_RUNS_DIR = path.join(REMOTE_ROOT, "runs");
 export const SSH_CONFIG_PATH = process.env.IMPEL_REMOTE_SSH_CONFIG || path.join(os.homedir(), ".ssh", "config");
 
-const RUN_ID_RE = /^run_[a-z0-9]{16}$/u;
+const RUN_ID_RE = /^run_[A-Za-z0-9_-]{8,128}$/u;
 const SSH_START_PREFIX = "# >>> impel remote ";
 const SSH_END_PREFIX = "# <<< impel remote ";
 
@@ -74,6 +74,8 @@ export function runPaths(runId) {
     fileList: path.join(root, "files.list"),
     archive: path.join(root, "working-tree.tar"),
     deletedList: path.join(root, "deleted.list"),
+    workspaceRoot: path.join(root, "workspace"),
+    providerCheckpoint: path.join(root, "provider-checkpoint.tar"),
   };
 }
 
@@ -196,7 +198,17 @@ export function removeRunSecrets(runId) {
     paths.fileList,
     paths.archive,
     paths.deletedList,
+    paths.providerCheckpoint,
   ]) {
     try { fs.rmSync(target, { force: true }); } catch { /* Best-effort local cleanup. */ }
   }
+  try { fs.rmSync(paths.workspaceRoot, { recursive: true, force: true }); } catch { /* Best-effort local cleanup. */ }
+}
+
+export function removeTransferArtifacts(runId) {
+  const paths = runPaths(runId);
+  for (const target of [paths.bundle, paths.fileList, paths.archive, paths.deletedList, paths.providerCheckpoint]) {
+    try { fs.rmSync(target, { force: true }); } catch { /* Best-effort local cleanup. */ }
+  }
+  try { fs.rmSync(paths.workspaceRoot, { recursive: true, force: true }); } catch { /* Best-effort local cleanup. */ }
 }

package/src/remote/telemetry.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { REMOTE_ROOT, validateRunId } from "./state.js";
+import { normalizeTenantId } from "../tenants.js";
+
+const TELEMETRY_PATH = process.env.IMPEL_REMOTE_TELEMETRY_PATH
+  || path.join(REMOTE_ROOT, "telemetry.jsonl");
+
+/**
+ * The rollback metric deliberately has a closed schema. Never pass arbitrary
+ * command options here: they can contain repository paths, prompts, provider
+ * payloads, environment values, or credentials.
+ */
+export function recordPortableLegacyInvocation({ tenantId, runId, now = new Date() }) {
+  const record = {
+    schemaVersion: 1,
+    counter: "remote.portable_legacy.invocation",
+    tenantId: normalizeTenantId(tenantId),
+    runId: validateRunId(runId),
+    recordedAt: now.toISOString(),
+  };
+  fs.mkdirSync(path.dirname(TELEMETRY_PATH), { recursive: true, mode: 0o700 });
+  fs.appendFileSync(TELEMETRY_PATH, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+  try { fs.chmodSync(TELEMETRY_PATH, 0o600); } catch { /* Best effort on Windows. */ }
+  return record;
+}
+
+export const PORTABLE_LEGACY_TELEMETRY_PATH = TELEMETRY_PATH;

package/src/remote/transfer.js

@@ -6,6 +6,11 @@ import { redactSecretText } from "../config.js";
 import { runBuffer, runCapture, runInteractive, sleep } from "./process.js";
 import { runPaths } from "./state.js";
 
+// LEGACY ONLY: this module's SSH upload and PAT-bearing remote configuration
+// are isolated to portable-legacy. Broker-backed modes use immutable workspace
+// artifacts and opaque provider-checkpoint uploads instead.
+export const LEGACY_SSH_TRANSFER_ONLY = true;
+
 const REMOTE_REPO = "/workspace/repo";
 const REMOTE_BUNDLE = "/tmp/impel-remote-repo.bundle";
 const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;
@@ -52,6 +57,8 @@ export function inspectRepository(requestedPath = process.cwd()) {
   const requested = path.resolve(requestedPath);
   const candidate = fs.realpathSync(requested);
   const root = fs.realpathSync(git(["-C", candidate, "rev-parse", "--show-toplevel"]));
+  const gitPrefix = git(["-C", candidate, "rev-parse", "--show-prefix"])
+    .replaceAll("\\", "/").replace(/\/+$/u, "");
   const head = git(["-C", root, "rev-parse", "HEAD"]);
   const branchResult = runCapture(process.env.IMPEL_REMOTE_GIT_BIN || "git", [
     "-C", root, "symbolic-ref", "--quiet", "--short", "HEAD",
@@ -65,10 +72,11 @@ export function inspectRepository(requestedPath = process.cwd()) {
   const userEmailResult = runCapture(process.env.IMPEL_REMOTE_GIT_BIN || "git", [
     "-C", root, "config", "--get", "user.email",
   ], { allowFailure: true });
-  const relativeProjectPath = path.relative(root, candidate) || ".";
-  if (relativeProjectPath === ".." || relativeProjectPath.startsWith(`..${path.sep}`)) {
-    throw new Error(`${candidate} is not inside its Git repository`);
-  }
+  // Git is the authority for worktree membership and the path relative to its
+  // root. Comparing canonical filesystem strings is not reliable on Windows:
+  // Node can preserve an 8.3 path such as RUNNER~1 while Git returns the long
+  // equivalent, making the same directory appear to be outside the worktree.
+  const relativeProjectPath = gitPrefix || ".";
   return {
     root,
     head,
@@ -76,10 +84,10 @@ export function inspectRepository(requestedPath = process.cwd()) {
     origin: originResult.status === 0 ? originResult.stdout.trim() : null,
     userName: userNameResult.status === 0 ? userNameResult.stdout.trim() : null,
     userEmail: userEmailResult.status === 0 ? userEmailResult.stdout.trim() : null,
-    relativeProjectPath: relativeProjectPath.split(path.sep).join("/"),
+    relativeProjectPath,
     remoteProjectPath: relativeProjectPath === "."
       ? REMOTE_REPO
-      : `${REMOTE_REPO}/${relativeProjectPath.split(path.sep).join("/")}`,
+      : `${REMOTE_REPO}/${relativeProjectPath}`,
   };
 }