mecord-connect 1.0.0

package/runtime/app/src/capabilities/git-write.js

@@ -0,0 +1,321 @@
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+                                                                                                         
+import { evidence } from '../core/evidence.js';
+import { OperatorError } from '../core/errors.js';
+import { resolveSupportedGitExecutable } from '../core/trusted-executable.js';
+import { GitCheckpointProvider } from './git-checkpoint.js';
+
+const SCORE                  = {
+  reliability: 0.99,
+  latency: 0.94,
+  determinism: 0.99,
+  security: 0.97,
+  reversibility: 0.97,
+  informationQuality: 0.99,
+  interactionCost: 0.01
+};
+
+const DISABLED_HOOKS_PATH = process.platform === 'win32' ? 'NUL' : '/dev/null';
+const SAFE_GIT_PREFIX = ['--no-pager', '--no-lazy-fetch', '-c', 'core.fsmonitor=false', '-c', `core.hooksPath=${DISABLED_HOOKS_PATH}`, '--literal-pathspecs'];
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+
+                  
+               
+                
+                    
+                       
+                      
+  
+
+                                                                  
+
+export class GitWriteProvider                               {
+           name = 'git.write.native';
+  #checkpoint                       ;
+
+  constructor(options                            ) {
+    this.#checkpoint = new GitCheckpointProvider(options);
+  }
+
+  supports(action               )          {
+    return action.capability === 'git.write';
+  }
+
+  advertises(action               )          {
+    if (!this.supports(action)) return false;
+    try { resolveSupportedGitExecutable(gitEnvironment({})); return true; } catch { return false; }
+  }
+  score()                  { return SCORE; }
+
+  async execute(action               )                        {
+    const started = performance.now();
+    try {
+      resolveSupportedGitExecutable(gitEnvironment({}));
+      const operation = String(action.input.operation ?? '');
+      if (!['stage', 'unstage', 'commit'].includes(operation)) {
+        throw new OperatorError('INVALID_GIT_WRITE_OPERATION', 'operation must be stage, unstage, or commit.');
+      }
+      const cwd = String(action.input.cwd ?? '');
+      const expectedCurrentFingerprint = String(action.input.expectedCurrentFingerprint ?? '');
+      if (!/^[0-9a-f]{64}$/i.test(expectedCurrentFingerprint)) {
+        throw new OperatorError('GIT_WRITE_FINGERPRINT_REQUIRED', 'expectedCurrentFingerprint from git.checkpoint inspect is required.');
+      }
+
+      const before = await this.#inspectState(cwd);
+      if (before.fingerprint !== expectedCurrentFingerprint) {
+        throw new OperatorError('GIT_WRITE_STATE_CHANGED', 'Repository state changed after the supplied write precondition was captured.', {
+          retryable: true,
+          details: { expectedCurrentFingerprint, actualCurrentFingerprint: before.fingerprint }
+        });
+      }
+
+      const checkpointResult = await this.#checkpoint.execute({
+        id: `${action.id}:checkpoint`,
+        capability: 'git.checkpoint.create',
+        risk: 'write',
+        input: { cwd, label: `automatic checkpoint before git ${operation}` },
+        provenance: { kind: 'runtime', source: action.id }
+      });
+      if (!checkpointResult.ok) {
+        throw new OperatorError(checkpointResult.error?.code ?? 'GIT_CHECKPOINT_FAILED', checkpointResult.error?.message ?? 'Unable to create pre-write checkpoint.');
+      }
+      const checkpoint = checkpointResult.output                  ;
+
+      if (operation === 'stage') return await this.#stage(action, started, before, checkpoint.id);
+      if (operation === 'unstage') return await this.#unstage(action, started, before, checkpoint.id);
+      return await this.#commit(action, started, before, checkpoint.id);
+    } catch (error) {
+      const op = error instanceof OperatorError
+        ? error
+        : new OperatorError('GIT_WRITE_ERROR', error instanceof Error ? error.message : String(error));
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: this.name,
+        evidence: [evidence('git_write', 'fail', op.message, { code: op.code })],
+        error: { code: op.code, message: op.message, retryable: op.retryable },
+        durationMs: Math.round(performance.now() - started)
+      };
+    }
+  }
+
+  async #stage(action               , started        , before           , checkpointId        )                        {
+    const paths = validatePaths(action.input.paths);
+    const all = action.input.all === true;
+    if (!all && paths.length === 0) throw new OperatorError('GIT_PATHS_REQUIRED', 'stage requires paths or all=true.');
+    await runGit(before.root, ['add', '-A', '--', ...(all ? ['.'] : paths)], {});
+    const after = await this.#inspectState(before.root);
+    const staged = await runGit(before.root, ['diff', '--cached', '--name-only', '-z', '--no-ext-diff', '--no-textconv'], {});
+    const stagedPaths = staged.stdout.split('\0').filter(Boolean).slice(0, 500);
+    return success(action, started, 'stage', before, after, checkpointId, {
+      stagedPaths,
+      all
+    });
+  }
+
+  async #unstage(action               , started        , before           , checkpointId        )                        {
+    if (!before.head) throw new OperatorError('GIT_UNBORN_UNSTAGE_UNSUPPORTED', 'unstage currently requires an existing HEAD commit.');
+    const paths = validatePaths(action.input.paths);
+    const all = action.input.all === true;
+    if (!all && paths.length === 0) throw new OperatorError('GIT_PATHS_REQUIRED', 'unstage requires paths or all=true.');
+    await runGit(before.root, ['restore', '--staged', '--', ...(all ? ['.'] : paths)], {});
+    const after = await this.#inspectState(before.root);
+    return success(action, started, 'unstage', before, after, checkpointId, { all, paths: all ? [] : paths });
+  }
+
+  async #commit(action               , started        , before           , checkpointId        )                        {
+    const message = String(action.input.message ?? '').trim();
+    if (!message || message.length > 4000 || message.includes('\0')) {
+      throw new OperatorError('INVALID_COMMIT_MESSAGE', 'commit message must contain 1-4000 characters and no NUL bytes.');
+    }
+    const staged = await runGit(before.root, ['diff', '--cached', '--quiet', '--no-ext-diff', '--no-textconv'], {}, true);
+    if (staged.code === 0) throw new OperatorError('GIT_NOTHING_STAGED', 'No staged changes are available to commit.');
+    if (staged.code !== 1) throw new OperatorError('GIT_STAGED_CHECK_FAILED', staged.stderr.trim() || `git diff exited ${staged.code}.`);
+
+    const identity = await commitIdentityEnv(before.root);
+    const hooksDir = await fs.mkdtemp(path.join(os.tmpdir(), 'operator-empty-hooks-'));
+    try {
+      await runGit(before.root, [
+        '-c', `core.hooksPath=${hooksDir}`,
+        '-c', 'commit.gpgSign=false',
+        'commit', '--no-verify', '--no-gpg-sign', '-m', message
+      ], identity);
+    } finally {
+      await fs.rm(hooksDir, { recursive: true, force: true });
+    }
+
+    const newHead = (await runGit(before.root, ['rev-parse', 'HEAD'], {})).stdout.trim();
+    if (!/^[0-9a-f]{40,64}$/i.test(newHead) || newHead === before.head) {
+      throw new OperatorError('GIT_COMMIT_POSTCONDITION_FAILED', 'Git commit did not advance HEAD as expected.');
+    }
+    const committedTree = (await runGit(before.root, ['rev-parse', 'HEAD^{tree}'], {})).stdout.trim();
+    if (committedTree !== before.indexTree) {
+      throw new OperatorError('GIT_COMMIT_POSTCONDITION_FAILED', 'Committed tree does not match the staged index captured by the precondition.', {
+        details: { expectedIndexTree: before.indexTree, committedTree }
+      });
+    }
+    if (before.head) {
+      const parent = (await runGit(before.root, ['rev-parse', 'HEAD^'], {})).stdout.trim();
+      if (parent !== before.head) {
+        throw new OperatorError('GIT_COMMIT_POSTCONDITION_FAILED', 'New commit parent does not match the pre-write HEAD.', {
+          details: { expectedParent: before.head, actualParent: parent }
+        });
+      }
+    }
+    const after = await this.#inspectState(before.root);
+    return success(action, started, 'commit', before, after, checkpointId, {
+      newHead,
+      previousHead: before.head,
+      committedTree,
+      hooksDisabled: true,
+      gpgSigningDisabled: true
+    });
+  }
+
+  async #inspectState(cwd        )                     {
+    const result = await this.#checkpoint.execute({
+      id: crypto.randomUUID(),
+      capability: 'git.checkpoint.inspect',
+      risk: 'read',
+      input: { cwd },
+      provenance: { kind: 'runtime' }
+    });
+    if (!result.ok) throw new OperatorError(result.error?.code ?? 'GIT_STATE_INSPECTION_FAILED', result.error?.message ?? 'Unable to inspect Git state.');
+    return (result.output                          ).current;
+  }
+}
+
+function validatePaths(input         )           {
+  const raw = Array.isArray(input) ? input.map(String) : [];
+  if (raw.length > 200) throw new OperatorError('TOO_MANY_GIT_PATHS', 'At most 200 paths may be supplied.');
+  return raw.map((item) => {
+    const value = item.trim();
+    if (!value || value.length > 1000 || value.includes('\0') || value.includes('\r') || value.includes('\n')) {
+      throw new OperatorError('INVALID_GIT_PATH', 'Git paths must be non-empty bounded single-line relative paths.');
+    }
+    if (path.isAbsolute(value) || value.startsWith(':')) throw new OperatorError('INVALID_GIT_PATH', 'Absolute paths and Git pathspec magic are not allowed.');
+    const normalized = path.normalize(value);
+    if (normalized === '..' || normalized.startsWith(`..${path.sep}`) || path.isAbsolute(normalized)) {
+      throw new OperatorError('INVALID_GIT_PATH', 'Git path escapes the repository root.');
+    }
+    return value;
+  });
+}
+
+function success(
+  action               ,
+  started        ,
+  operation        ,
+  before           ,
+  after           ,
+  checkpointId        ,
+  details                         
+)               {
+  return {
+    ok: true,
+    capability: action.capability,
+    provider: 'git.write.native',
+    output: {
+      operation,
+      before,
+      after,
+      checkpointId,
+      ...details
+    },
+    evidence: [
+      evidence('git_write', 'pass', `Structured Git ${operation} completed without a command shell.`, { operation, checkpointId }),
+      evidence('recovery_checkpoint', 'pass', 'A non-mutating checkpoint was created before the Git write.', { checkpointId }),
+      evidence('postcondition', 'pass', 'Repository state was re-inspected after the Git write.', { beforeFingerprint: before.fingerprint, afterFingerprint: after.fingerprint })
+    ],
+    durationMs: Math.round(performance.now() - started)
+  };
+}
+
+async function commitIdentityEnv(root        )                             {
+  const [nameResult, emailResult] = await Promise.all([
+    runGit(root, ['config', '--local', '--get', 'user.name'], {}, true),
+    runGit(root, ['config', '--local', '--get', 'user.email'], {}, true)
+  ]);
+  for (const result of [nameResult, emailResult]) {
+    if (![0, 1].includes(result.code)) {
+      throw new OperatorError('GIT_CONFIG_INSPECTION_FAILED', result.stderr.trim() || 'Unable to inspect repository-local Git identity.');
+    }
+  }
+  let name = 'Operator';
+  let email = 'operator@local.invalid';
+  if (nameResult.code === 0 && emailResult.code === 0) {
+    const localName = nameResult.stdout.trim();
+    const localEmail = emailResult.stdout.trim();
+    if (!localName || localName.length > 200 || /[\0\r\n]/.test(localName)) throw new OperatorError('GIT_IDENTITY_INVALID', 'Repository-local Git user.name is invalid.');
+    if (!localEmail || localEmail.length > 320 || /[\0\r\n]/.test(localEmail)) throw new OperatorError('GIT_IDENTITY_INVALID', 'Repository-local Git user.email is invalid.');
+    name = localName;
+    email = localEmail;
+  }
+  return {
+    GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email,
+    GIT_COMMITTER_NAME: name, GIT_COMMITTER_EMAIL: email
+  };
+}
+
+function gitEnvironment(extraEnv                   )                    {
+  const nullConfig = process.platform === 'win32' ? 'NUL' : '/dev/null';
+  const env                    = {
+    GIT_PAGER: '',
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_CONFIG_GLOBAL: nullConfig,
+    GIT_CONFIG_SYSTEM: nullConfig,
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_NO_LAZY_FETCH: '1'
+  };
+  for (const key of ['PATH', 'Path', 'PATHEXT', 'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'USER', 'USERNAME', 'LOGNAME', 'TMP', 'TEMP', 'TMPDIR', 'LANG', 'LC_ALL', 'LC_CTYPE']) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+  for (const [key, value] of Object.entries(extraEnv)) {
+    if (value !== undefined) env[key] = value;
+  }
+  return env;
+}
+
+async function runGit(cwd        , args          , extraEnv                   , allowNonZero = false)                     {
+  return await new Promise((resolve, reject) => {
+    const environment = gitEnvironment(extraEnv);
+    const gitExecutable = resolveSupportedGitExecutable(environment);
+    const child = spawn(gitExecutable, [...SAFE_GIT_PREFIX, ...args], {
+      cwd,
+      shell: false,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: environment
+    });
+    const stdout           = [];
+    const stderr           = [];
+    let bytes = 0;
+    const capture = (bucket          ) => (chunk        ) => {
+      if (bytes >= MAX_OUTPUT_BYTES) return;
+      const sliced = chunk.subarray(0, MAX_OUTPUT_BYTES - bytes);
+      bucket.push(sliced);
+      bytes += sliced.byteLength;
+    };
+    child.stdout.on('data', capture(stdout));
+    child.stderr.on('data', capture(stderr));
+    child.once('error', reject);
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 1_000).unref();
+    }, 30_000);
+    timer.unref();
+    child.once('close', (code) => {
+      clearTimeout(timer);
+      const result = { code: code ?? -1, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') };
+      if (result.code !== 0 && !allowNonZero) {
+        reject(new OperatorError('GIT_COMMAND_FAILED', result.stderr.trim().slice(0, 1200) || `git ${args[0] ?? ''} exited ${result.code}.`));
+        return;
+      }
+      resolve(result);
+    });
+  });
+}

package/runtime/app/src/capabilities/git.js

@@ -0,0 +1,252 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+                                                                                                                                     
+import { assertPublicSafePath, containsRestrictedData } from '../core/public-restricted-data.js';
+import { OperatorError } from '../core/errors.js';
+import { resolveSupportedGitExecutable } from '../core/trusted-executable.js';
+import { ProcessProvider } from './process.js';
+
+const SCORE                  = {
+  reliability: 0.99,
+  latency: 0.98,
+  determinism: 0.99,
+  security: 0.97,
+  reversibility: 0.92,
+  informationQuality: 0.99,
+  interactionCost: 0.01
+};
+
+const NULL_GIT_CONFIG = process.platform === 'win32' ? 'NUL' : '/dev/null';
+const SAFE_GIT_PREFIX = ['--no-pager', '--no-lazy-fetch', '-c', 'core.fsmonitor=false', '-c', `core.hooksPath=${NULL_GIT_CONFIG}`];
+const PUBLIC_GIT_PREFIX = [...SAFE_GIT_PREFIX, '--literal-pathspecs'];
+const READ_ONLY_GIT_ENV = Object.freeze({
+  GIT_CONFIG_GLOBAL: NULL_GIT_CONFIG,
+  GIT_CONFIG_SYSTEM: NULL_GIT_CONFIG,
+  GIT_CONFIG_NOSYSTEM: '1',
+  GIT_ATTR_NOSYSTEM: '1',
+  GIT_OPTIONAL_LOCKS: '0',
+  GIT_NO_LAZY_FETCH: '1'
+});
+const PATHSPEC_META = /[*?\[\]{}]/;
+
+export class GitProvider                               {
+           name = 'git.native';
+  #process                 ;
+
+  constructor(options                            ) {
+    this.#process = new ProcessProvider({
+      allowedRoots: options.allowedRoots,
+      allowedExecutables: ['git'],
+      environmentOverrides: READ_ONLY_GIT_ENV
+    });
+  }
+
+  supports(action               )          {
+    return ['git.status', 'git.diff', 'git.rev-parse'].includes(action.capability);
+  }
+
+  advertises(action               )          {
+    if (!this.supports(action)) return false;
+    try { resolveSupportedGitExecutable(process.env); return true; } catch { return false; }
+  }
+
+  score()                  { return SCORE; }
+
+  async execute(action               , context                             = {})                        {
+    try { resolveSupportedGitExecutable(process.env); } catch (error) {
+      const op = error instanceof OperatorError
+        ? error
+        : new OperatorError('GIT_VERSION_CHECK_FAILED', error instanceof Error ? error.message : String(error));
+      return gitFailure(action, op.code, op.message);
+    }
+    const cwd = String(action.input.cwd ?? '');
+    const paths = Array.isArray(action.input.paths) ? action.input.paths.map(String) : [];
+    const publicLiteral = action.capability === 'git.diff' && action.input.publicLiteralFiles === true;
+
+    if (action.capability !== 'git.rev-parse') {
+      const filterFailure = await this.#rejectContentFilters(action, cwd, context);
+      if (filterFailure) return filterFailure;
+    }
+
+    if (publicLiteral) {
+      const validation = await validatePublicLiteralPaths(cwd, paths);
+      if (validation) return gitFailure(action, validation.code, validation.message);
+
+      const tracked = await this.#run(action, cwd, [
+        ...PUBLIC_GIT_PREFIX, 'ls-files', '-z', '--', ...paths
+      ], context);
+      if (!tracked.ok) return tracked;
+      const trackedNames = splitGitNul((tracked.output                                       )?.stdout);
+      const requested = new Set(paths.map(normalizeGitPath));
+      if (trackedNames.some((name) => !requested.has(name))) {
+        return gitFailure(action, 'GIT_PUBLIC_PATH_FILTER_INVALID', 'Public Git diff accepts explicit literal files only.');
+      }
+
+      const names = await this.#run(action, cwd, [
+        ...PUBLIC_GIT_PREFIX, 'diff', '--name-only', '-z', '--no-ext-diff', '--no-textconv', '--ignore-submodules=all', '--', ...paths
+      ], context);
+      if (!names.ok) return names;
+      const changed = splitGitNul((names.output                                       )?.stdout);
+      if (changed.some((name) => !requested.has(name))) {
+        return gitFailure(action, 'GIT_PUBLIC_PATH_FILTER_INVALID', 'Git selected a file outside the requested literal set.');
+      }
+    }
+
+    const prefix = publicLiteral ? PUBLIC_GIT_PREFIX : SAFE_GIT_PREFIX;
+    const args = action.capability === 'git.status'
+      ? [...SAFE_GIT_PREFIX, 'status', '--porcelain=v1', '-z', '--branch', '--ignore-submodules=all']
+      : action.capability === 'git.diff'
+        ? [...prefix, 'diff', '--no-ext-diff', '--no-textconv', '--ignore-submodules=all', '--', ...paths]
+        : [...SAFE_GIT_PREFIX, 'rev-parse', '--show-toplevel'];
+    const result = await this.#run(action, cwd, args, context);
+    return action.capability === 'git.status' && result.ok ? structuredGitStatus(result) : result;
+  }
+
+  async #rejectContentFilters(action               , cwd        , context                            )                                    {
+    const inspected = await this.#process.execute({
+      ...action,
+      capability: 'terminal.execute',
+      input: {
+        executable: 'git',
+        args: [...SAFE_GIT_PREFIX, 'config', '--name-only', '--get-regexp', '^filter\\..*\\.(clean|smudge|process)$'],
+        cwd,
+        timeoutMs: 30_000
+      }
+    }, context);
+    const output = inspected.output                                                                              ;
+    if (!inspected.ok && output?.exitCode !== 1) {
+      return gitFailure(action, 'GIT_CONFIG_INSPECTION_FAILED', String(output?.stderr ?? inspected.error?.message ?? 'Unable to inspect Git content-filter configuration.').trim());
+    }
+    const keys = String(output?.stdout ?? '').split(/\r?\n/).map((item) => item.trim()).filter(Boolean);
+    if (keys.length > 0) {
+      return gitFailure(action, 'GIT_CONTENT_FILTER_DENIED', 'Git status/diff deny repository content filters because they can execute arbitrary commands.');
+    }
+    return undefined;
+  }
+
+  async #run(action               , cwd        , args          , context                            )                        {
+    const result = await this.#process.execute({ ...action, capability: 'terminal.execute', input: { executable: 'git', args, cwd, timeoutMs: 30_000 } }, context);
+    return { ...result, capability: action.capability, provider: this.name };
+  }
+}
+
+function structuredGitStatus(result              )               {
+  const raw = result.output                                                         ;
+  const records = String(raw?.stdout ?? '').split('\0').filter(Boolean);
+  let branch                = null;
+  let detached = false;
+  if (records[0]?.startsWith('## ')) {
+    const parsed = safeStatusBranch(records.shift() .slice(3));
+    branch = parsed.branch;
+    detached = parsed.detached;
+  }
+  const entries                                 = [];
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index] ;
+    if (record.length < 4 || record[2] !== ' ') { entries.push({ kind: 'unknown', restricted: true }); continue; }
+    const status = record.slice(0, 2);
+    const pathValue = safeStatusPath(record.slice(3));
+    const entry                          = {
+      indexStatus: status[0],
+      worktreeStatus: status[1],
+      kind: status === '??' ? 'untracked' : status.includes('R') ? 'renamed' : status.includes('C') ? 'copied' : status.includes('U') ? 'unmerged' : 'tracked'
+    };
+    if (pathValue) entry.path = pathValue; else entry.restricted = true;
+    if ((status.includes('R') || status.includes('C')) && index + 1 < records.length) {
+      const original = safeStatusPath(records[++index] );
+      if (original) entry.originalPath = original; else entry.originalRestricted = true;
+    }
+    entries.push(entry);
+  }
+  return { ...result, output: { branch, detached, clean: entries.length === 0, entries, truncated: raw?.truncated === true } };
+}
+
+async function validatePublicLiteralPaths(
+  cwd        ,
+  paths          
+)                                                         {
+  if (paths.length === 0) {
+    return { code: 'GIT_PUBLIC_PATH_FILTER_REQUIRED', message: 'Public Git diff requires explicit literal file paths.' };
+  }
+  for (const raw of paths) {
+    const normalized = normalizeGitPath(raw);
+    const segments = normalized.split('/');
+    if (!raw || raw.trim() !== raw || normalized === '' || normalized === '.' || normalized === '..') {
+      return invalidPublicPath();
+    }
+    if (path.isAbsolute(raw) || /^[A-Za-z]:[\\/]/.test(raw) || /^\\\\/.test(raw)) {
+      return invalidPublicPath();
+    }
+    if (raw.startsWith(':') || raw.startsWith('!') || PATHSPEC_META.test(raw)) {
+      return invalidPublicPath();
+    }
+    if (segments.includes('..') || segments.includes('.')) return invalidPublicPath();
+    try {
+      assertPublicSafePath(normalized);
+    } catch {
+      return { code: 'RESTRICTED_DATA_PATH_DENIED', message: 'The public plugin cannot access credential or secret-bearing paths.' };
+    }
+    const resolved = path.resolve(cwd, ...segments);
+    const relative = path.relative(path.resolve(cwd), resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) return invalidPublicPath();
+    try {
+      const stat = await fs.lstat(resolved);
+      if (stat.isDirectory()) return invalidPublicPath();
+    } catch (error) {
+      const code = (error                         ).code;
+      if (code !== 'ENOENT') return invalidPublicPath();
+    }
+  }
+  return undefined;
+}
+
+function invalidPublicPath()                                    {
+  return {
+    code: 'GIT_PUBLIC_PATH_FILTER_INVALID',
+    message: 'Public Git diff accepts explicit project-relative literal file paths only.'
+  };
+}
+
+function splitGitNul(value         )           {
+  return String(value ?? '').split('\0').filter(Boolean).map(normalizeGitPath);
+}
+
+function normalizeGitPath(value        )         {
+  return value.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function gitFailure(action               , code        , message        )               {
+  return {
+    ok: false,
+    capability: action.capability,
+    provider: 'git.native',
+    evidence: [],
+    error: { code, message, retryable: false },
+    durationMs: 0
+  };
+}
+
+
+function safeStatusBranch(raw        )                                               {
+  let value = raw.trim();
+  if (value === 'HEAD (no branch)' || value.startsWith('HEAD detached ')) {
+    return { branch: null, detached: true };
+  }
+  value = value.replace(/^No commits yet on /, '').replace(/^Initial commit on /, '');
+  const tracking = value.indexOf('...');
+  if (tracking >= 0) value = value.slice(0, tracking);
+  const bracket = value.indexOf(' [');
+  if (bracket >= 0) value = value.slice(0, bracket);
+  const valid = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$/.test(value) && !containsRestrictedData(value);
+  return { branch: valid ? value : '[hidden]', detached: false };
+}
+
+
+function safeStatusPath(raw        )                     {
+  const normalized = normalizeGitPath(raw);
+  const segments = normalized.split('/');
+  if (!normalized || normalized.length > 4096) return undefined;
+  if (path.isAbsolute(normalized) || segments.includes('.') || segments.includes('..')) return undefined;
+  try { assertPublicSafePath(normalized); } catch { return undefined; }
+  return containsRestrictedData(normalized) ? undefined : normalized;
+}

package/runtime/app/src/capabilities/index.js

@@ -0,0 +1,16 @@
+export * from './path-scope.js';
+export * from './filesystem.js';
+export * from './process.js';
+export * from './git.js';
+export * from './git-checkpoint.js';
+export * from './git-write.js';
+export * from './system.js';
+export * from './project.js';
+export * from './project-command.js';
+export * from './project-transaction.js';
+export * from './docker.js';
+export * from './postgres.js';
+export * from './vscode.js';
+export * from './browser-cdp.js';
+export * from './browser-managed.js';
+export * from './windows-uia.js';

package/runtime/app/src/capabilities/path-scope.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { OperatorError } from '../core/errors.js';
+import { normalizeScopedPathSyntax } from '../core/scoped-path-syntax.js';
+import { withWindowsPathLease } from '../core/windows-path-lease.js';
+
+function lexicalInside(candidate        , root        )          {
+  const rel = path.relative(root, candidate);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+export class PathScope {
+           roots          ;
+  #windowsPathLeaseExecutable         ;
+
+  constructor(roots          , options                                          = {}) {
+    if (roots.length === 0) throw new OperatorError('NO_ALLOWED_ROOTS', 'At least one allowed root is required.');
+    this.roots = roots.map((root) => path.resolve(root));
+    this.#windowsPathLeaseExecutable = options.windowsPathLeaseExecutable;
+  }
+
+  async resolveExisting(inputPath        )                  {
+    const absolute = this.#absolute(inputPath);
+    const real = await fs.realpath(absolute);
+    const realRoots = await Promise.all(this.roots.map(async (root) => {
+      try { return await fs.realpath(root); } catch { return root; }
+    }));
+    if (!realRoots.some((root) => lexicalInside(real, root))) {
+      throw new OperatorError('PATH_OUTSIDE_SCOPE', 'Resolved path escapes the authorized roots.', { details: { inputPath, real } });
+    }
+    return real;
+  }
+
+  async resolveForWrite(inputPath        )                  {
+    const absolute = this.#absolute(inputPath);
+    const parent = await fs.realpath(path.dirname(absolute));
+    const realRoots = await Promise.all(this.roots.map(async (root) => {
+      try { return await fs.realpath(root); } catch { return root; }
+    }));
+    if (!realRoots.some((root) => lexicalInside(parent, root))) {
+      throw new OperatorError('PATH_OUTSIDE_SCOPE', 'Write target escapes the authorized roots.', { details: { inputPath, parent } });
+    }
+    return path.join(parent, path.basename(absolute));
+  }
+
+  async withExisting   (inputPath        , operation                                      )             {
+    const absolute = this.#absolute(inputPath);
+    const root = this.#lexicalRoot(absolute);
+    return await withWindowsPathLease({
+      root,
+      target: absolute,
+      mode: 'existing',
+      executable: this.#windowsPathLeaseExecutable
+    }, async () => await operation(await this.resolveExisting(absolute)));
+  }
+
+  async withForWrite   (inputPath        , operation                                      )             {
+    const absolute = this.#absolute(inputPath);
+    const root = this.#lexicalRoot(absolute);
+    return await withWindowsPathLease({
+      root,
+      target: absolute,
+      mode: 'parent',
+      executable: this.#windowsPathLeaseExecutable
+    }, async () => await operation(await this.resolveForWrite(absolute)));
+  }
+
+  #absolute(inputPath        )         {
+    const syntax = normalizeScopedPathSyntax(inputPath);
+    if (syntax.kind === 'native-absolute') return syntax.value;
+    if (syntax.kind === 'foreign-windows-absolute') {
+      throw new OperatorError('PATH_OUTSIDE_SCOPE', 'Foreign absolute paths are outside the authorized roots.');
+    }
+    if (this.roots.length !== 1) {
+      throw new OperatorError('PATH_OUTSIDE_SCOPE', 'Relative paths require exactly one authorized root.');
+    }
+    return path.resolve(this.roots[0] , syntax.value);
+  }
+
+  #lexicalRoot(absolute        )         {
+    const candidates = this.roots.filter((root) => lexicalInside(absolute, root));
+    candidates.sort((a, b) => b.length - a.length);
+    if (!candidates[0]) throw new OperatorError('PATH_OUTSIDE_SCOPE', 'Requested path escapes the authorized roots.');
+    return candidates[0];
+  }
+}