@notis_ai/cli 0.2.13 → 0.2.14

package/src/runtime/app-platform.js

@@ -7,7 +7,7 @@
  */
 
 import { spawn } from 'node:child_process';
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -15,7 +15,7 @@ import { gunzipSync } from 'node:zlib';
 
 import { usageError } from './errors.js';
 import { validateArtifactBoundary, validateProjectBoundary } from './app-boundary-validator.js';
-import { readAppChangelog } from './app-changelog.js';
+import { CHANGELOG_MERGE_DATE, readAppChangelog } from './app-changelog.js';
 
 const NOTIS_DIR = '.notis';
 const STATE_FILE = join(NOTIS_DIR, 'state.json');
@@ -44,6 +44,9 @@ const SOURCE_COPY_EXCLUDES = new Set([
   'dist',
   'tsconfig.tsbuildinfo',
   '.DS_Store',
+  // Interpreter droppings: a stray `python -m py_compile` in a skill's
+  // scripts/ directory must not ship version-specific bytecode in the bundle.
+  '__pycache__',
 ]);
 const SCAFFOLD_COPY_EXCLUDES = new Set([
   ...SOURCE_COPY_EXCLUDES,
@@ -51,6 +54,17 @@ const SCAFFOLD_COPY_EXCLUDES = new Set([
   '.next',
   '.turbo',
 ]);
+// Listing media describes the scaffold's own Store entry, so a new project must
+// never inherit it. Scaffold packaging still ships these files -- only the
+// `apps init` copy drops them. Screenshots only: `screenshot-fixtures.json` is
+// not listing media, it is the stub data the dev harness serves, and dropping
+// it would make every route of a fresh project render its empty state.
+const SCAFFOLD_LISTING_MEDIA = /^metadata\/screenshot-\d+\.png$/i;
+// A directory-declared skill ships every supporting file to the sandbox, so it
+// needs a ceiling of its own. Kept well above the 512 KB SKILL.md limit so a
+// handful of scripts always fits, and far below the bundle machinery's own
+// limits so an accidental asset dump fails on the client with a clear message.
+export const MAX_APP_SKILL_BUNDLE_BYTES = 5 * 1024 * 1024;
 let appConfigImportNonce = 0;
 
 // ---------------------------------------------------------------------------
@@ -427,6 +441,39 @@ export function resolveListingScreenshots(projectDir, appConfig = null) {
   });
 }
 
+/**
+ * Screenshot scenarios named in notis.config.ts that metadata/screenshot-fixtures.json
+ * does not define. A missing scenario is silent at capture time -- the harness
+ * simply falls back to the default fixtures -- so it is reported as a warning.
+ */
+export function findUnknownScreenshotScenarios(projectDir, screenshots = []) {
+  const named = screenshots.filter((entry) => entry?.scenario);
+  if (named.length === 0) {
+    return [];
+  }
+  const fixturesPath = join(projectDir, METADATA_DIR, 'screenshot-fixtures.json');
+  if (!existsSync(fixturesPath)) {
+    return ['metadata/screenshot-fixtures.json is missing, so screenshot scenarios cannot be applied.'];
+  }
+  let defined;
+  try {
+    const parsed = JSON.parse(readFileSync(fixturesPath, 'utf-8'));
+    const scenarios = parsed?.scenarios && typeof parsed.scenarios === 'object' ? parsed.scenarios : {};
+    defined = new Set(Object.keys(scenarios));
+  } catch {
+    return ['metadata/screenshot-fixtures.json is not valid JSON, so screenshot scenarios cannot be applied.'];
+  }
+  const warnings = [];
+  for (const entry of named) {
+    if (!defined.has(entry.scenario)) {
+      warnings.push(
+        `${entry.path} names scenario "${entry.scenario}", which metadata/screenshot-fixtures.json does not define.`,
+      );
+    }
+  }
+  return warnings;
+}
+
 export function inspectListingReadiness(projectDir, appConfig = null) {
   const config = appConfig || {};
   const warnings = [];
@@ -738,7 +785,7 @@ export function generateManifest(appConfig, projectDir) {
   const displayTitle = appConfig.title || appConfig.displayName || appConfig.name;
   const skills = (Array.isArray(appConfig.skills) ? appConfig.skills : []).map((skill) => ({
     key: skill.key,
-    path: String(skill.path || '').replace(/^\.\/+/, ''),
+    path: normalizeAppSkillManifestPath(skill.path),
     name: skill.name,
     description: skill.description || null,
   }));
@@ -830,12 +877,54 @@ export function normalizeAppCapabilities(capabilities) {
   if (capabilities.workspaceDatabases === 'read') {
     normalized.workspaceDatabases = 'read';
   }
+  if (capabilities.cloudComputer === 'read' || capabilities.cloudComputer === 'shell') {
+    normalized.cloudComputer = capabilities.cloudComputer;
+  }
   return normalized;
 }
 
+/**
+ * Manifest form of a declared skill path: no leading `./`, no trailing slash.
+ * A directory declaration is the same string as the source-tree prefix the
+ * server matches the uploaded source files against.
+ */
+export function normalizeAppSkillManifestPath(sourcePath) {
+  return String(sourcePath || '').replace(/\\/g, '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+}
+
+/**
+ * Every packageable file under a declared skill directory, relative to that
+ * directory, in stable order. Excludes match `readSourceFiles` so the files a
+ * dev session sends inline are exactly the ones a deploy uploads as source.
+ */
+function readAppSkillDirectoryFiles(skillDir) {
+  const entries = [];
+
+  function walk(dir, prefix) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (shouldExcludeSourceEntry(entry.name) || entry.isSymbolicLink()) {
+        continue;
+      }
+      const fullPath = join(dir, entry.name);
+      const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(fullPath, relPath);
+      } else if (entry.isFile()) {
+        entries.push({ path: relPath, absolutePath: fullPath });
+      }
+    }
+  }
+
+  walk(skillDir, '');
+  // Byte order, not locale order: the server sorts the same file set the same
+  // way before hashing it, so a dev session and a deploy agree on the hash.
+  return entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
 export function resolveConfiguredAppSkills(appConfig, projectDir) {
   const configured = Array.isArray(appConfig.skills) ? appConfig.skills : [];
   const projectRoot = resolve(projectDir);
+  const realProjectRoot = realpathSync(projectRoot);
   const seenKeys = new Set();
 
   return configured.map((skill, index) => {
@@ -855,7 +944,49 @@ export function resolveConfiguredAppSkills(appConfig, projectDir) {
     if (!relativePath || relativePath.startsWith('../') || relativePath === '..') {
       throw usageError(`App skill path must stay inside the project: ${sourcePath}`);
     }
-    if (!existsSync(absolutePath) || !statSync(absolutePath).isFile()) {
+    if (!existsSync(absolutePath)) {
+      throw usageError(`App skill entrypoint not found: ${sourcePath}`);
+    }
+    if (lstatSync(absolutePath).isSymbolicLink()) {
+      throw usageError(`App skill entrypoint cannot be a symbolic link: ${sourcePath}`);
+    }
+    const realAbsolutePath = realpathSync(absolutePath);
+    const realRelativePath = relative(realProjectRoot, realAbsolutePath).replace(/\\/g, '/');
+    if (!realRelativePath || realRelativePath.startsWith('../') || realRelativePath === '..') {
+      throw usageError(`App skill path must stay inside the project after resolving links: ${sourcePath}`);
+    }
+
+    const description = typeof skill.description === 'string' ? skill.description.trim() : null;
+    const stats = statSync(absolutePath);
+    if (stats.isDirectory()) {
+      const entries = readAppSkillDirectoryFiles(absolutePath);
+      if (!entries.some((entry) => entry.path === 'SKILL.md')) {
+        throw usageError(`App skill directory must contain SKILL.md: ${sourcePath}`);
+      }
+      const bundleFiles = entries.map((entry) => ({
+        path: entry.path,
+        content: readFileSync(entry.absolutePath),
+      }));
+      const totalBytes = bundleFiles.reduce((total, entry) => total + entry.content.length, 0);
+      if (totalBytes > MAX_APP_SKILL_BUNDLE_BYTES) {
+        throw usageError(
+          `App skill "${key}" bundles ${totalBytes} bytes, above the ${MAX_APP_SKILL_BUNDLE_BYTES} byte limit.`,
+        );
+      }
+      const skillMd = bundleFiles.find((entry) => entry.path === 'SKILL.md');
+      return {
+        key,
+        path: relativePath,
+        name,
+        description,
+        skill_md: skillMd.content.toString('utf8'),
+        bundle_files: bundleFiles.map((entry) => ({
+          path: entry.path,
+          content_b64: entry.content.toString('base64'),
+        })),
+      };
+    }
+    if (!stats.isFile()) {
       throw usageError(`App skill entrypoint not found: ${sourcePath}`);
     }
 
@@ -863,7 +994,7 @@ export function resolveConfiguredAppSkills(appConfig, projectDir) {
       key,
       path: relativePath,
       name,
-      description: typeof skill.description === 'string' ? skill.description.trim() : null,
+      description,
       skill_md: readFileSync(absolutePath, 'utf8'),
     };
   });
@@ -1024,12 +1155,85 @@ export function scaffoldProject({ projectDir, appName, fromSlug = null }) {
         config = config.replace(/'My Notis App'/, displayName);
       }
     }
+    config = removeConfigArrayProperty(config, 'screenshots');
     writeFileSync(configPath, config);
   }
 
+  resetScaffoldChangelog(projectDir, appName);
+
   return { projectDir };
 }
 
+/**
+ * Drop `property: [ ... ]` from a notis.config.ts source.
+ *
+ * The scan tracks bracket depth while skipping string literals, so entries
+ * whose text contains a bracket (alt text, selectors) cannot end the array
+ * early. When the array cannot be resolved the source is returned untouched --
+ * a stale screenshots list is a warning at verify time, a broken config is not.
+ */
+function removeConfigArrayProperty(source, property) {
+  const start = source.search(new RegExp(`^[ \\t]*${property}[ \\t]*:[ \\t]*\\[`, 'm'));
+  if (start === -1) {
+    return source;
+  }
+  let index = source.indexOf('[', start);
+  let depth = 0;
+  let quote = null;
+  for (; index < source.length; index += 1) {
+    const char = source[index];
+    if (quote) {
+      if (char === '\\') {
+        index += 1;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '\'' || char === '"' || char === '`') {
+      quote = char;
+      continue;
+    }
+    if (char === '[') {
+      depth += 1;
+    } else if (char === ']') {
+      depth -= 1;
+      if (depth === 0) {
+        break;
+      }
+    }
+  }
+  if (depth !== 0) {
+    return source;
+  }
+  let end = index + 1;
+  if (source[end] === ',') {
+    end += 1;
+  }
+  while (end < source.length && (source[end] === ' ' || source[end] === '\t')) {
+    end += 1;
+  }
+  if (source[end] === '\n') {
+    end += 1;
+  }
+  return source.slice(0, start) + source.slice(end);
+}
+
+/**
+ * A new project starts its own release history: the scaffold's entries describe
+ * releases of a different app.
+ */
+function resetScaffoldChangelog(projectDir, appName) {
+  const changelogPath = join(projectDir, 'CHANGELOG.md');
+  if (!existsSync(changelogPath)) {
+    return;
+  }
+  writeFileSync(
+    changelogPath,
+    `# ${appName} Changelog\n\n## [Initial Release] - ${CHANGELOG_MERGE_DATE}\n\n- First Store release.\n`,
+  );
+}
+
 function normalizeScaffoldLockfile(projectDir, pkg) {
   const lockPath = join(projectDir, 'package-lock.json');
   if (!existsSync(lockPath)) {
@@ -1126,6 +1330,9 @@ function copyScaffoldSource(sourceDir, targetDir) {
   function shouldCopy(path) {
     const name = path.split(/[\\/]/).pop();
     if (!name) return true;
+    if (SCAFFOLD_LISTING_MEDIA.test(relative(sourceDir, path).replace(/\\/g, '/'))) {
+      return false;
+    }
     return !SCAFFOLD_COPY_EXCLUDES.has(name)
       && !name.startsWith('.env')
       && !/\.(test|spec)\.[cm]?[jt]sx?$/i.test(name);
@@ -1187,7 +1394,12 @@ export function collectArtifactFiles(projectDir) {
 }
 
 function shouldExcludeSourceEntry(name) {
-  return SOURCE_COPY_EXCLUDES.has(name) || name.startsWith('.env');
+  return (
+    SOURCE_COPY_EXCLUDES.has(name)
+    || name.startsWith('.env')
+    || name.endsWith('.pyc')
+    || name.endsWith('.pyo')
+  );
 }
 
 function readSourceFiles(projectDir) {

package/src/runtime/delegated-context.js

@@ -0,0 +1,68 @@
+/**
+ * Detect that this CLI is running *as* a Notis agent rather than for a person.
+ *
+ * Hand-over is the one command where that distinction matters: an agent Notis
+ * is already running has no business handing the same work back to Notis, and
+ * nothing about the loop it would create is self-limiting.
+ *
+ * This is the polite half of the guard. The server refuses the same call unless
+ * it carries a purpose-scoped CLI/MCP OAuth token, which a delegated runtime
+ * never has -- that is the half that actually holds. What this adds is a clear
+ * message at the point of the mistake, instead of a permission error the agent
+ * will try to work around.
+ */
+
+import { existsSync } from 'node:fs';
+import { CliError, EXIT_CODES } from './errors.js';
+
+// The cloud computer's root. Present only inside the user's Vercel sandbox.
+const SANDBOX_ROOT = '/vercel/sandbox';
+
+export function delegatedContextReason(env = process.env, { fileExists = existsSync } = {}) {
+  if (env.NOTIS_DELEGATED_CONTEXT === '1') {
+    // Set by Notis Desktop on every coding agent it spawns. Those runs use the
+    // user's own OAuth profile, so nothing else distinguishes them.
+    return 'this process was started by Notis as a delegated coding agent';
+  }
+  if (fileExists(SANDBOX_ROOT)) {
+    return 'this process is running on the Notis cloud computer';
+  }
+  if (env.NOTIS_AGENT === '1' && env.NOTIS_JWT) {
+    return 'this process is authenticated as a Notis agent, not as you';
+  }
+  return null;
+}
+
+export function assertNotDelegated(commandLabel, env = process.env) {
+  const reason = delegatedContextReason(env);
+  if (!reason) {
+    return;
+  }
+  throw new CliError({
+    code: 'handover_from_delegated_context',
+    message:
+      `\`notis ${commandLabel}\` hands work to a Notis agent, and ${reason}. ` +
+      'An agent cannot hand its own task back to Notis.',
+    exitCode: EXIT_CODES.usage,
+    hints: [
+      { message: 'Run the hand-over from the terminal on your own machine.' },
+      { message: 'If you are the agent: just do the work here, in this workspace.' },
+    ],
+  });
+}
+
+/**
+ * Tools that hand work to a Notis agent, by canonical name.
+ *
+ * `notis handover` is not the only way to reach these: `notis tools exec` takes
+ * any tool name, and `tools exec-parallel` takes a list of them. Guarding only
+ * the friendly command would leave the escape hatch it exists to wrap.
+ */
+export const HANDOVER_TOOL_NAMES = new Set(['LOCAL_NOTIS_HAND_OVER']);
+
+export function assertToolNotDelegated(toolName, env = process.env) {
+  if (!HANDOVER_TOOL_NAMES.has(String(toolName || '').toUpperCase())) {
+    return;
+  }
+  assertNotDelegated(`tools exec ${toolName}`, env);
+}

package/src/runtime/git.js

@@ -0,0 +1,233 @@
+/**
+ * Local git inspection for `notis handover`.
+ *
+ * The CLI has no other reason to know about git, so this stays deliberately
+ * small: read where we are, push the branch, and report what the remote is.
+ * Everything else about the repository is the cloud workspace's problem.
+ *
+ * Every call is `spawnSync` on the real `git` binary rather than a library.
+ * The user's credentials, hooks, SSH agent and includeIf config are what make a
+ * push succeed on their machine, and only their own git honors all of them.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { lstatSync, readFileSync } from 'node:fs';
+import { basename, relative, resolve, sep } from 'node:path';
+import { CliError, EXIT_CODES } from './errors.js';
+
+const GIT_TIMEOUT_MS = 120_000;
+const MAX_SECRET_SCAN_BYTES = 1_000_000;
+const SAFE_ENV_TEMPLATES = /^\.env\.(?:example|sample|template)$/i;
+const SENSITIVE_PATH = /^(?:\.env(?:\..+)?|\.envrc|\.git-credentials|\.npmrc|\.pypirc|\.netrc|credentials(?:\..+)?|secrets?(?:\..+)?|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|.*\.(?:pem|key|p12|pfx|jks))$/i;
+const SENSITIVE_CONTENT = [
+  /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/,
+  /\b[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:[^/\s@]+@/i,
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /\bgh[pousr]_[A-Za-z0-9]{36,}\b/,
+  /\bsk-[A-Za-z0-9_-]{20,}\b/,
+];
+
+export function runGit(
+  args,
+  { cwd = process.cwd(), timeoutMs = GIT_TIMEOUT_MS, trimOutput = true } = {},
+) {
+  const result = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    env: {
+      ...process.env,
+      // A push that stops to ask for a password would hang a non-interactive
+      // agent run forever. Fail fast instead and let the hint explain.
+      GIT_TERMINAL_PROMPT: '0',
+    },
+  });
+  if (result.error && result.error.code === 'ENOENT') {
+    throw new CliError({
+      code: 'git_not_found',
+      message: 'git is not installed or not on PATH.',
+      exitCode: EXIT_CODES.usage,
+    });
+  }
+  return {
+    exitCode: result.status ?? 1,
+    stdout: trimOutput ? (result.stdout || '').trim() : (result.stdout || ''),
+    stderr: trimOutput ? (result.stderr || '').trim() : (result.stderr || ''),
+  };
+}
+
+function gitOrNull(args, options) {
+  const result = runGit(args, options);
+  return result.exitCode === 0 ? result.stdout : null;
+}
+
+function nulSeparatedGitPaths(args, repository) {
+  const result = runGit([...args, '-z'], { cwd: repository.toplevel, trimOutput: false });
+  if (result.exitCode !== 0 || !result.stdout) return [];
+  return result.stdout.split('\0').filter(Boolean);
+}
+
+/** Exact files `git add -A` would include, expanding untracked directories. */
+function filesToAutoCommit(repository) {
+  return [...new Set([
+    ...nulSeparatedGitPaths(['diff', '--name-only'], repository),
+    ...nulSeparatedGitPaths(['diff', '--cached', '--name-only'], repository),
+    ...nulSeparatedGitPaths(['ls-files', '--others', '--exclude-standard'], repository),
+  ])];
+}
+
+/** Refuse files that are unsafe to publish automatically without user review. */
+export function sensitiveAutoCommitFiles(repository) {
+  const root = resolve(repository.toplevel);
+  const sensitive = [];
+  for (const path of filesToAutoCommit(repository)) {
+    const absolute = resolve(root, path);
+    const insideRoot = relative(root, absolute);
+    if (insideRoot === '..' || insideRoot.startsWith(`..${sep}`) || insideRoot === '') continue;
+    const name = basename(path);
+    if (SENSITIVE_PATH.test(name) && !SAFE_ENV_TEMPLATES.test(name)) {
+      sensitive.push(path);
+      continue;
+    }
+    try {
+      const stat = lstatSync(absolute);
+      if (!stat.isFile() || stat.size > MAX_SECRET_SCAN_BYTES) continue;
+      const content = readFileSync(absolute, 'utf8');
+      if (SENSITIVE_CONTENT.some((pattern) => pattern.test(content))) sensitive.push(path);
+    } catch {
+      // Deleted files and paths racing with an editor have no content to leak.
+    }
+  }
+  return sensitive;
+}
+
+/**
+ * Parse an origin URL into {owner, repo}. Handles the three forms git remotes
+ * actually take: scp-style ssh, ssh:// and https://.
+ */
+export function parseRemoteUrl(url) {
+  if (typeof url !== 'string' || !url) {
+    return null;
+  }
+  const trimmed = url.trim().replace(/\.git$/, '');
+  const scp = trimmed.match(/^[^@]+@([^:]+):(.+)$/);
+  const path = scp ? scp[2] : trimmed.replace(/^[a-z+]+:\/\/(?:[^@/]+@)?[^/]+\//i, '');
+  const host = scp ? scp[1] : (trimmed.match(/^[a-z+]+:\/\/(?:[^@/]+@)?([^/]+)/i) || [])[1];
+  const segments = path.split('/').filter(Boolean);
+  if (segments.length < 2) {
+    return null;
+  }
+  return {
+    host: host || null,
+    owner: segments[segments.length - 2],
+    repo: segments[segments.length - 1],
+  };
+}
+
+/** Everything `handover start` needs to know about where it is running. */
+export function inspectRepository(cwd = process.cwd()) {
+  const toplevel = gitOrNull(['rev-parse', '--show-toplevel'], { cwd });
+  if (!toplevel) {
+    throw new CliError({
+      code: 'not_a_git_repository',
+      message: 'Hand-over runs from inside a git repository.',
+      exitCode: EXIT_CODES.usage,
+      hints: [{ message: 'cd into the repository you want Notis to work on, then run the command again.' }],
+    });
+  }
+
+  const branch = gitOrNull(['branch', '--show-current'], { cwd: toplevel });
+  if (!branch) {
+    throw new CliError({
+      code: 'detached_head',
+      message: 'HEAD is detached, so there is no branch to hand over.',
+      exitCode: EXIT_CODES.usage,
+      hints: [{ message: 'Check out a branch first: git switch -c my-feature' }],
+    });
+  }
+
+  const remoteUrl = gitOrNull(['remote', 'get-url', 'origin'], { cwd: toplevel });
+  if (!remoteUrl) {
+    throw new CliError({
+      code: 'no_origin_remote',
+      message: 'This repository has no "origin" remote, so the cloud agent cannot fetch the branch.',
+      exitCode: EXIT_CODES.usage,
+      hints: [{ message: 'Add one: git remote add origin <url>' }],
+    });
+  }
+
+  const status = runGit(['status', '--porcelain'], { cwd: toplevel });
+  const dirtyFiles = status.stdout
+    ? status.stdout.split('\n').map((line) => line.slice(3).trim()).filter(Boolean)
+    : [];
+
+  return {
+    toplevel,
+    branch,
+    remoteUrl,
+    remote: parseRemoteUrl(remoteUrl),
+    dirtyFiles,
+    head: gitOrNull(['rev-parse', 'HEAD'], { cwd: toplevel }),
+    upstream: gitOrNull(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'], {
+      cwd: toplevel,
+    }),
+  };
+}
+
+/** Commit everything in the working tree, including untracked files. */
+export function commitWorkingTree(repository, message) {
+  const sensitiveFiles = sensitiveAutoCommitFiles(repository);
+  if (sensitiveFiles.length) {
+    throw new CliError({
+      code: 'sensitive_working_tree',
+      message: 'Refusing to publish files that may contain credentials or private keys.',
+      exitCode: EXIT_CODES.conflict,
+      details: { sensitive_files: sensitiveFiles.slice(0, 20) },
+      hints: [
+        { message: 'Review, remove, or ignore these files before handing over.' },
+        { message: 'To publish them deliberately, commit and push them yourself first.' },
+      ],
+    });
+  }
+  const add = runGit(['add', '-A'], { cwd: repository.toplevel });
+  if (add.exitCode !== 0) {
+    throw new CliError({
+      code: 'git_add_failed',
+      message: `Could not stage the working tree: ${add.stderr || add.stdout}`,
+      exitCode: EXIT_CODES.unexpected,
+    });
+  }
+  const commit = runGit(['commit', '-m', message], { cwd: repository.toplevel });
+  if (commit.exitCode !== 0) {
+    throw new CliError({
+      code: 'git_commit_failed',
+      message: `Could not commit the working tree: ${commit.stderr || commit.stdout}`,
+      exitCode: EXIT_CODES.unexpected,
+      hints: [{ message: 'Commit the changes yourself, then run the hand-over again.' }],
+    });
+  }
+  return gitOrNull(['rev-parse', 'HEAD'], { cwd: repository.toplevel });
+}
+
+/**
+ * Push the branch to origin. The cloud workspace fetches from origin, so an
+ * unpushed commit simply does not exist as far as the hand-over is concerned.
+ */
+export function pushBranch(repository, branch) {
+  const args = repository.upstream
+    ? ['push', 'origin', branch]
+    : ['push', '--set-upstream', 'origin', branch];
+  const result = runGit(args, { cwd: repository.toplevel });
+  if (result.exitCode !== 0) {
+    throw new CliError({
+      code: 'git_push_failed',
+      message: `Could not push ${branch} to origin: ${result.stderr || result.stdout}`,
+      exitCode: EXIT_CODES.conflict,
+      hints: [
+        { message: 'The cloud agent works from origin, so the branch has to be pushed first.' },
+        { message: 'If the remote moved ahead, reconcile locally (git pull --rebase) and retry.' },
+      ],
+    });
+  }
+  return true;
+}

package/src/runtime/transport.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { createReadStream } from 'node:fs';
 import { dirname } from 'node:path';
 import { CliError, EXIT_CODES } from './errors.js';
+import { delegatedContextReason } from './delegated-context.js';
 import {
   credentialIsExpired,
   getJwtExpiration,
@@ -327,9 +328,11 @@ export async function httpRequest({
     });
 
     let payload = null;
+    let payloadReadError = null;
     try {
       payload = await response.json();
-    } catch {
+    } catch (error) {
+      payloadReadError = error;
       payload = null;
     }
 
@@ -350,9 +353,11 @@ export async function httpRequest({
           signal: controller.signal,
           ...(requestBody.duplex ? { duplex: requestBody.duplex } : {}),
         });
+        payloadReadError = null;
         try {
           payload = await response.json();
-        } catch {
+        } catch (error) {
+          payloadReadError = error;
           payload = null;
         }
       }
@@ -376,6 +381,14 @@ export async function httpRequest({
       throw normalizeBackendError(response.status, payload, runtime);
     }
 
+    // A successful status is not a successful tool call until its response
+    // body has been read. Mutations may already have committed before a socket
+    // reset truncates the JSON; surface that as an ambiguous network failure
+    // so callers never persist an undefined result or attempt a second write.
+    if (response.status !== 204 && payloadReadError) {
+      throw payloadReadError;
+    }
+
     return {
       requestId,
       payload: payload || {},
@@ -428,6 +441,10 @@ export async function callTool({
       cwd: process.cwd(),
       agent_mode: runtime.agentMode,
       cli_version: runtime.cliVersion,
+      // Reported so the server can refuse work-handing tools from a run Notis
+      // is itself driving. Advisory -- a determined agent can unset the markers
+      // -- so the server treats it as one layer, not the whole guard.
+      ...(delegatedContextReason() ? { delegated_context: true } : {}),
       ...(runtime.debugEntitlementOverride
         ? { debug_entitlement_override: runtime.debugEntitlementOverride }
         : {}),