@6reduk/workspace-pipeline 0.1.0

package/src/providers/native.js

@@ -0,0 +1,155 @@
+import { posix } from 'node:path';
+import { parseTOML } from 'toml-eslint-parser';
+import { fail, parse, MAX_INPUT_BYTES } from '../contracts/parse.js';
+import { portablePath } from '../contracts/semantic.js';
+import { sourceText, snapshotFilePath } from './source.js';
+import { legacyEntryReplay } from './common-entry.js';
+
+const capabilities = Object.freeze(['skills', 'agents', 'mcp', 'entry-instructions']);
+const safeName = name => typeof name === 'string' && /^[a-z][a-z0-9-]{0,62}$/.test(name) &&
+  !['constructor', 'prototype', 'default'].includes(name);
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+function shape(value, required, optional = []) {
+  if (!object(value) || required.some(key => !Object.hasOwn(value, key)) ||
+      Object.keys(value).some(key => ![...required, ...optional].includes(key))) fail('provider.format');
+}
+function text(value, limit = MAX_INPUT_BYTES) {
+  if (typeof value !== 'string' || !value.trim() || Buffer.byteLength(value) > limit || /\u0000/.test(value)) fail('provider.format');
+  return value;
+}
+function metadata(value) {
+  shape(value, ['name', 'description']);
+  if (!safeName(value.name)) fail('provider.name');
+  text(value.description, 1024);
+  return value;
+}
+function markdown(input) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(input);
+  if (!match) fail('provider.frontmatter');
+  const meta = metadata(parse(match[1])); text(match[2]);
+  return { ...meta, body: match[2] };
+}
+function tree(context, prefix) {
+  portablePath(prefix);
+  const entries = [...context.files.keys()].filter(name => name.startsWith(prefix + '/')).sort();
+  if (!entries.length) fail('provider.source-missing');
+  return entries;
+}
+const file = (owner, path, content) => ({ owner, path, kind: 'file', bytes: Buffer.from(content) });
+function route(context, source, destination) {
+  const target = posix.relative(posix.dirname(destination), snapshotFilePath(context, source));
+  return `Read [the complete pipeline instruction](<${target}>) before acting.\n` +
+    'Resolve its relative links from that source file, not from this routing file or the shell working directory.\n' +
+    'The source is a resource location, not the project root. Use the wrapper AGENTS.md for project routing.\n' +
+    'Follow its gates and scope; this routing file grants no approval.\n';
+}
+const providerRoot = id => {
+  const root = { codex: '.agents', claude: '.claude', kimi: '.kimi-code', grok: '.grok' }[id];
+  if (typeof root !== 'string') fail('provider.unsupported');
+  return root;
+};
+export function skills(context, id, prefix) {
+  const entries = tree(context, prefix), roots = new Map();
+  for (const source of entries) {
+    const relative = source.slice(prefix.length + 1), parts = relative.split('/');
+    if (!safeName(parts[0]) || parts.length < 2) fail('provider.skill-tree');
+    roots.set(parts[0], `${prefix}/${parts[0]}/SKILL.md`);
+  }
+  return [...roots].map(([name, source]) => {
+    const meta = markdown(sourceText(context, source));
+    if (meta.name !== name) fail('provider.name');
+    const destination = `${providerRoot(id)}/skills/${name}/SKILL.md`;
+    return file(id, destination, `---\nname: ${name}\ndescription: ${JSON.stringify(meta.description)}\n---\n\n` + route(context, source, destination));
+  });
+}
+export function agents(context, id, prefix) {
+  const requests = [], fields = [];
+  for (const source of tree(context, prefix)) {
+    const relative = source.slice(prefix.length + 1), extension = id === 'codex' ? '.toml' : '.md';
+    if (relative.includes('/') || !relative.endsWith(extension)) fail('provider.agent-tree');
+    const name = relative.slice(0, -extension.length), input = sourceText(context, source);
+    let meta;
+    if (id === 'codex') {
+      if (Buffer.byteLength(input) > MAX_INPUT_BYTES) fail('provider.format');
+      let ast;
+      try { ast = parseTOML(input, { tomlVersion: '1.0' }); }
+      catch { fail('provider.agent-toml'); }
+      const value = Object.create(null), pairs = ast.body[0].body;
+      if (pairs.length !== 3) fail('provider.format');
+      for (const pair of pairs) {
+        if (pair.type !== 'TOMLKeyValue' || pair.key.keys.length !== 1 || pair.value.type !== 'TOMLValue' || pair.value.kind !== 'string') fail('provider.format');
+        const key = pair.key.keys[0].name ?? pair.key.keys[0].value;
+        if (!['name', 'description', 'developer_instructions'].includes(key) || Object.hasOwn(value, key)) fail('provider.format');
+        value[key] = pair.value.value;
+      }
+      shape(value, ['name', 'description', 'developer_instructions']);
+      meta = metadata({ name: value.name, description: value.description });
+      text(value.developer_instructions);
+      if (meta.name !== name || name === 'enabled') fail('provider.name');
+      const destination = `.codex/agents/${name}.toml`;
+      // TOML basic strings use JSON-compatible escaping for accepted text.
+      const instructions = route(context, source, destination) + '\n' + value.developer_instructions;
+      if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(instructions)) fail('provider.format');
+      requests.push(file(id, destination, `developer_instructions = ${JSON.stringify(instructions)}\n`));
+      fields.push({ pointer: `/agents/${name}`, present: true,
+        value: { description: meta.description, config_file: `agents/${name}.toml` } });
+    } else {
+      meta = markdown(input);
+      if (meta.name !== name) fail('provider.name');
+      if (id === 'kimi' && ['agent', 'coder', 'explore', 'plan'].includes(name)) fail('provider.name');
+      if (id === 'grok' && ['general-purpose', 'explore', 'plan'].includes(name)) fail('provider.name');
+      const destination = `${providerRoot(id)}/agents/${name}.md`;
+      requests.push(file(id, destination, `---\nname: ${name}\ndescription: ${JSON.stringify(meta.description)}\n---\n\n` + route(context, source, destination)));
+    }
+  }
+  return { requests, fields };
+}
+export function mcp(context, id, source) {
+  const config = parse(sourceText(context, source), 'json'); shape(config, ['mcpServers']);
+  if (!object(config.mcpServers) || !Object.keys(config.mcpServers).length) fail('provider.mcp');
+  return Object.entries(config.mcpServers).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([name, server]) => {
+    if (!safeName(name)) fail('provider.name');
+    let value;
+    if (server?.type === 'stdio') {
+      shape(server, ['type', 'command'], ['args', 'env']); text(server.command, 4096);
+      if (server.args !== undefined && (!Array.isArray(server.args) || server.args.some(arg => typeof arg !== 'string' || arg.includes('\0')))) fail('provider.mcp');
+      if (server.env !== undefined && (!object(server.env) || Object.entries(server.env).some(([key, v]) =>
+        !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof v !== 'string' || v.includes('\0')))) fail('provider.mcp');
+      const { type, ...stdio } = server; value = ['codex', 'kimi', 'grok'].includes(id) ? stdio : server;
+    } else if (server?.type === 'http') {
+      shape(server, ['type', 'url']);
+      text(server.url, 8192);
+      let url; try { url = new URL(server.url); } catch { fail('provider.mcp'); }
+      if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash) fail('provider.mcp');
+      value = ['codex', 'kimi', 'grok'].includes(id) ? { url: server.url } : server;
+    } else fail('provider.mcp');
+    return { pointer: `/${['codex', 'grok'].includes(id) ? 'mcp_servers' : 'mcpServers'}/${name}`, present: true, value };
+  });
+}
+function render(context, id) {
+  const declaration = context.pipeline.providers[id];
+  if (!declaration || declaration.requires.some(capability => !capabilities.includes(capability))) fail('provider.unsupported');
+  const requests = [], fields = [];
+  if (declaration.skills !== null) requests.push(...skills(context, id, declaration.skills));
+  if (declaration.agents !== null) {
+    const rendered = agents(context, id, declaration.agents); requests.push(...rendered.requests); fields.push(...rendered.fields);
+  }
+  if (declaration.mcp !== null) {
+    const entries = mcp(context, id, declaration.mcp);
+    if (id === 'codex') fields.push(...entries);
+    else requests.push({ owner: id, path: '.mcp.json', kind: 'json-fields', fields: entries });
+  }
+  if (id === 'codex' && fields.length) requests.push({ owner: id, path: '.codex/config.toml', kind: 'toml-fields', fields });
+  if (declaration.entryInstructions !== null) text(sourceText(context, declaration.entryInstructions));
+  // Codex reads common AGENTS.md; provider entry pointers are appended there.
+  if (id === 'claude' && !context.layout.bundles && legacyEntryReplay(context)) requests.push(file(id, 'CLAUDE.md', '@AGENTS.md\n' +
+    (declaration.entryInstructions === null ? '' : '\n' + route(context, declaration.entryInstructions, 'CLAUDE.md'))));
+  return requests;
+}
+function adapter(id) {
+  return Object.freeze({ id, version: id === 'claude' ? '2' : '1', capabilities,
+    async validate(context) { render(context, id); return { valid: true, runtime: 'not-run' }; },
+    async plan(context) { return render(context, id); } });
+}
+export const codexAdapter = adapter('codex');
+export const claudeAdapter = adapter('claude');

package/src/providers/registry.js

@@ -0,0 +1,10 @@
+import { codexAdapter, claudeAdapter } from './native.js';
+import { sharedAdapter } from './shared.js';
+import { kimiAdapter } from './kimi.js';
+import { grokAdapter } from './grok.js';
+
+// Compiled CLI code only. No registry/module names may be supplied by a package.
+export const providerRegistry = Object.freeze({
+  adapters: Object.freeze({ codex: codexAdapter, claude: claudeAdapter, kimi: kimiAdapter, grok: grokAdapter }),
+  sharedAdapter
+});

package/src/providers/shared.js

@@ -0,0 +1,51 @@
+import { renderEntry, portablePath } from '../contracts/semantic.js';
+import { fail } from '../contracts/parse.js';
+import { sourceText, snapshotResourcePath, snapshotFilePath } from './source.js';
+import { commonEntryPath, commonEntryText, needsCommonEntry, legacyEntryReplay } from './common-entry.js';
+
+// Common entry has one owner, regardless of the number of selected providers.
+// Ownership/conflict/approval policy remains in the ordinary planner, not here.
+export const sharedAdapter = Object.freeze({
+  async plan(context) {
+    const selection = context.layout.agentsDocument;
+    let body;
+    if (selection.mode === 'source') body = sourceText(context, selection.path);
+    else if (selection.mode === 'default') body = '# Workspace instructions\n\n' +
+      'Start harness sessions from this wrapper. Read the selected repository instructions before making changes.\n' +
+      'Read documentation from its overview toward the relevant detailed artifacts; do not scan every document by default.\n' +
+      'Do not infer approval, runtime readiness or task completion from installation metadata.\n';
+    else fail('entry.input');
+    body = renderEntry(body, context.layout.layout);
+    const lines = ['\n\n## Workspace routing\n',
+      'Paths below are relative to this wrapper, not to the shell working directory.'];
+    for (const [id, repo] of Object.entries(context.layout.repositories).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+      portablePath(repo.relative);
+      lines.push(`- Repository \`${id}\`: \`${repo.relative}\` (${repo.role}).`);
+    }
+    portablePath(context.layout.documentation.relative);
+    lines.push(`- Project documentation: \`${context.layout.documentation.relative}\`.`);
+    for (const [id, root] of Object.entries(context.layout.projectRoots).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+      portablePath(root.relative);
+      lines.push(`- Project root \`${id}\`: \`${root.relative}\`.`);
+    }
+    lines.push(`- Pipeline resources: \`${snapshotResourcePath(context)}\`.`,
+      'The snapshot identifier locates installed resources; it does not pin project documents or grant task approval.');
+    // Keep common entry stable when one installed provider is removed. These are
+    // available source routes, not a claim that all providers are enabled.
+    for (const id of Object.keys(context.pipeline.providers ?? {}).sort()) {
+      const entry = context.pipeline.providers[id].entryInstructions;
+      if (entry !== null) lines.push(`If using ${id}, read its [provider instructions](<${snapshotFilePath(context, entry)}>) before acting. This link does not enable that provider.`);
+    }
+    const bytes = Buffer.from(body + lines.join('\n') + '\n', 'utf8');
+    if (bytes.length > 2 * 1024 * 1024) fail('entry.input');
+    const requests = [{ path: 'AGENTS.md', owner: 'shared', kind: 'file', bytes }];
+    const bundle = Object.values(context.layout.bundles ?? {})[0];
+    if (bundle) {
+      const entry = renderEntry(sourceText(context, bundle.entry.source), context.layout.layout);
+      if (!entry.trim() || entry.includes('\0')) fail('entry.input');
+      requests.push({ path: bundle.entry.target, owner: 'shared', kind: 'file', bytes: Buffer.from(entry) });
+    } else if (needsCommonEntry(context.layout.providers ?? context.workspace.providers) && !legacyEntryReplay(context))
+      requests.push({ path: commonEntryPath, owner: 'shared', kind: 'file', bytes: Buffer.from(commonEntryText) });
+    return requests;
+  }
+});

package/src/providers/source.js

@@ -0,0 +1,30 @@
+import { posix } from 'node:path';
+import { fail } from '../contracts/parse.js';
+import { portablePath } from '../contracts/semantic.js';
+import { utf8 } from '../source/inventory.js';
+
+// Reads exclusively from the already verified Git tree supplied by preparePlan.
+// No checkout paths, network requests, source modules or filesystem fallback.
+export function sourceBytes(context, name) {
+  portablePath(name);
+  const bytes = context.files.get(name);
+  if (!Buffer.isBuffer(bytes)) fail('provider.source-missing');
+  return Buffer.from(bytes);
+}
+export function sourceText(context, name) { return utf8(sourceBytes(context, name)); }
+
+export function snapshotFilePath(context, name) {
+  snapshotResourcePath(context);
+  sourceBytes(context, name);
+  return posix.join(context.snapshot.path, name);
+}
+
+export function snapshotResourcePath(context) {
+  const { snapshot, pipeline } = context;
+  if (!snapshot || !/^sha256:[a-f0-9]{64}$/.test(snapshot.digest) ||
+      snapshot.path !== '.pipeline/snapshots/' + snapshot.digest.slice(7)) fail('provider.snapshot');
+  portablePath(pipeline.resources);
+  const prefix = pipeline.resources + '/';
+  if (![...context.files.keys()].some(name => name.startsWith(prefix))) fail('provider.resources');
+  return posix.join(snapshot.path, pipeline.resources);
+}

package/src/source/git.js

@@ -0,0 +1,303 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, mkdir, readdir, stat, realpath, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { performance } from 'node:perf_hooks';
+import { ContractError, fail } from '../contracts/parse.js';
+import { validateStructure } from '../contracts/validate.js';
+import { portablePath } from '../contracts/semantic.js';
+import { LIMITS, cap, utf8, verifyPackage } from './inventory.js';
+import { materialize } from './snapshot.js';
+import { repositoryBudget } from './repository-budget.js';
+
+const oid = value => /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value);
+// Git for Windows understands /dev/null, but not Node's \\.\nul spelling.
+const devNull = '/dev/null';
+export function validateSource(source) {
+  // Reuse the reviewed Git union via its public workspace envelope, no new schema.
+  validateStructure('workspace', { schemaVersion: 1, pipeline: source, providers: ['codex'], profile: 'source-validation' });
+  if (source.subdirectory !== '.') portablePath(source.subdirectory);
+  if (source.ref !== 'HEAD' && !oid(source.ref)) {
+    if (source.ref.startsWith('refs/') && !/^refs\/(?:heads|tags)\//.test(source.ref)) fail('source.ref');
+    if (source.ref.endsWith('.') || source.ref.split('/').some(p => p.startsWith('.') || p.endsWith('.lock'))) fail('source.ref');
+  }
+  if (source.transport === 'remote') {
+    let url;
+    try { url = new URL(source.url); } catch { fail('source.url'); }
+    const rawAuthority = source.url.split('/')[2];
+    const port = /:(\d+)$/.exec(rawAuthority)?.[1];
+    if (port !== undefined && (+port < 1 || +port > 65535)) fail('source.port');
+    if (url.hostname.split('.').some(label => !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i.test(label))) fail('source.host');
+    let decoded;
+    try { decoded = decodeURIComponent(url.pathname); } catch { fail('source.url'); }
+    if (/[%\\\s\u0000-\u001f\u007f\u0085\ufeff?#]/u.test(decoded)) fail('source.url');
+  }
+  return source;
+}
+export function environment(network, alternate) {
+  const env = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (!/^GIT_/i.test(k) || ['GIT_SSH', 'GIT_SSH_COMMAND', 'GIT_SSH_VARIANT', 'GIT_ASKPASS',
+      ...(network ? ['GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_NOSYSTEM'] : [])].includes(k.toUpperCase())) env[k] = v;
+  }
+  Object.assign(env, { GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1',
+    GIT_NO_LAZY_FETCH: '1', GIT_LITERAL_PATHSPECS: '1', GIT_TERMINAL_PROMPT: '0' });
+  // Local object reads need no authentication or global Git configuration.
+  if (!network) Object.assign(env, { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: devNull });
+  // Git accepts C-quoted entries, preventing separators in a path from becoming
+  // additional object stores. This is internal discovery, never package input.
+  if (alternate) env.GIT_ALTERNATE_OBJECT_DIRECTORIES = JSON.stringify(alternate.replaceAll('\\', '/'));
+  return env;
+}
+async function bytesIn(directory) {
+  let size = 0;
+  for (const e of await readdir(directory, { withFileTypes: true })) {
+    const p = path.join(directory, e.name);
+    if (e.isSymbolicLink()) fail('source.preparation-link');
+    try { size += e.isDirectory() ? await bytesIn(p) : (await stat(p)).size; }
+    catch (e) { if (e.code !== 'ENOENT') throw e; } // pack temporary file renamed
+  }
+  return size;
+}
+export function gitArgs(cwd, args) {
+  return ['--no-pager', '--no-replace-objects', '--no-lazy-fetch', '--literal-pathspecs', '-C', cwd,
+    '-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=' + devNull,
+    '-c', 'maintenance.auto=false', '-c', 'gc.auto=0', '-c', 'fetch.writeCommitGraph=false',
+    '-c', 'protocol.ext.allow=never', ...args];
+}
+// Output and stored-object caps are independent. On Windows terminate the owned
+// child process tree; never kill by process name or touch unrelated sessions.
+export function runGit(cwd, args, options = {}, runtime = {}) {
+  return runBoundedGit(LIMITS, cwd, args, options, runtime);
+}
+export function runRepositoryGit(cwd, args, options = {}, runtime = {}) {
+  const budget = repositoryBudget(options);
+  return runBoundedGit({...LIMITS, blob:256*1024*1024, pack:budget.packLimit, gitMs:budget.gitMs, acquisitionMs:budget.acquisitionMs},
+    cwd, args, {...options, packLimit:budget.packLimit}, runtime);
+}
+async function runBoundedGit(limits, cwd, args, { deadline = performance.now() + limits.acquisitionMs,
+  outputLimit = LIMITS.metadata, network = false, objects, packLimit = LIMITS.pack, allowMissing = false, alternate,
+  diagnoseUnadvertised = false } = {}, runtime = {}) {
+  cap(packLimit, limits.pack, 'source.pack-limit');
+  cap(outputLimit, limits.blob, 'source.output-limit');
+  const timeout = Math.min(limits.gitMs, deadline - performance.now());
+  if (timeout <= 0) fail('source.timeout');
+  return new Promise((resolve, reject) => {
+    const launch = runtime.spawn ?? spawn;
+    const child = launch('git', gitArgs(cwd, args), {
+      shell: false, windowsHide: true, env: environment(network, alternate), stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32'
+    });
+    let failure, length = 0, stderrLength = 0, chunks = [], monitoring = false, closed = false, settled = false, terminationTimer;
+    let stderrTail = '', unadvertised = false;
+    const stop = code => {
+      if (failure || closed) return;
+      failure = code;
+      // A surviving descendant can retain the pipe after Git exits. Never wait
+      // indefinitely for close; report uncertainty rather than pretending it died.
+      terminationTimer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer); clearInterval(monitor);
+        child.stdout.destroy(); child.stderr.destroy(); child.unref();
+        const error = new ContractError('source.termination-unconfirmed');
+        error.processId = child.pid;
+        reject(error);
+      }, 2000);
+      if (child.pid) {
+        if ((runtime.platform ?? process.platform) === 'win32') {
+          const killer = launch('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore', shell: false });
+          killer.on('error', () => child.kill());
+          killer.on('exit', code => { if (code !== 0 && !closed) child.kill(); });
+        } else { try { process.kill(-child.pid, 'SIGKILL'); } catch { child.kill(); } }
+      }
+    };
+    const timer = setTimeout(() => stop('source.timeout'), timeout);
+    const monitor = objects ? setInterval(async () => {
+      if (monitoring || failure) return;
+      monitoring = true;
+      try { if (await bytesIn(objects) > packLimit) stop('source.pack'); }
+      catch { stop('source.pack-monitor'); }
+      finally { monitoring = false; }
+    }, 25) : null;
+    child.stdout.on('data', b => {
+      length += b.length;
+      if (length > outputLimit) stop('source.output');
+      else chunks.push(b);
+    });
+    child.stderr.on('data', b => {
+      stderrLength += b.length;
+      if (stderrLength > LIMITS.metadata) { stop('source.stderr'); return; }
+      if (diagnoseUnadvertised) {
+        // Recognize a fixed native diagnostic only. Never expose remote stderr,
+        // URLs or credentials; chunk boundaries must not change classification.
+        const text = stderrTail + b.toString('utf8');
+        unadvertised ||= /Server does not allow request for unadvertised object/i.test(text);
+        stderrTail = text.slice(-128);
+      }
+    });
+    child.on('error', () => { settled = true; clearTimeout(timer); clearTimeout(terminationTimer); clearInterval(monitor); reject(new ContractError('source.git-unavailable')); });
+    child.on('close', async code => {
+      closed = true;
+      clearTimeout(timer); clearTimeout(terminationTimer); clearInterval(monitor);
+      if (settled) return;
+      settled = true;
+      try {
+        if (objects && await bytesIn(objects) > packLimit) failure = 'source.pack';
+        if (failure) fail(failure);
+        if (code !== 0 && !(allowMissing && code === 1)) fail(unadvertised ? 'source.unadvertised-commit' : 'source.git-failed');
+        resolve({ code, bytes: Buffer.concat(chunks) });
+      } catch (e) { reject(e instanceof ContractError ? e : new ContractError('source.git-failed')); }
+    });
+  });
+}
+// Source Git is used only for bounded metadata discovery. Ref peeling and all
+// object interpretation run in a fresh bare repo: no source config/index/hooks
+// are copied. The temporary read-only alternate is never part of the snapshot.
+async function localRepo(sourceRepo, ref, preparation, options) {
+  const inspect = async args => utf8((await runGit(sourceRepo, args, options)).bytes).trim();
+  const bare = await inspect(['rev-parse', '--is-bare-repository']) === 'true';
+  const root = await inspect(['rev-parse', bare ? '--absolute-git-dir' : '--show-toplevel']);
+  if (await realpath(root) !== sourceRepo) fail('source.repository-root');
+  const common = await inspect(['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  const alternate = await realpath(path.join(common, 'objects'));
+  const format = await inspect(['rev-parse', '--show-object-format=storage']);
+  if (!['sha1', 'sha256'].includes(format)) fail('source.object-format');
+  const repo = path.join(preparation, 'objects.git');
+  await mkdir(repo);
+  await runGit(repo, ['init', '--bare', '--template=', '--object-format=' + format], options);
+  const names = ref === 'HEAD' || oid(ref) || ref.startsWith('refs/') ? [ref] : ['refs/heads/' + ref, 'refs/tags/' + ref];
+  for (const name of names) {
+    if (oid(name)) continue;
+    const found = await runGit(sourceRepo, ['rev-parse', '--verify', '--quiet', '--end-of-options', name], { ...options, allowMissing: true });
+    if (found.code !== 0) continue;
+    const value = utf8(found.bytes).trim();
+    if (!oid(value)) fail('source.ref-output');
+    // Packed refs and reftable are read by native Git, not guessed on disk.
+    const target = path.join(repo, ...name.split('/'));
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, value + '\n');
+  }
+  const isolatedOptions = { ...options, alternate };
+  const commit = await resolveLocal(repo, ref, isolatedOptions);
+  return { repo, commit, alternate };
+}
+async function resolveLocal(repo, ref, options) {
+  async function candidate(name) {
+    const r = await runGit(repo, ['rev-parse', '--verify', '--quiet', '--end-of-options', name + '^{commit}'], { ...options, allowMissing: true });
+    return r.code === 0 ? utf8(r.bytes).trim() : null;
+  }
+  let values;
+  if (ref === 'HEAD' || oid(ref) || ref.startsWith('refs/')) values = [await candidate(ref)];
+  else {
+    values = [await candidate('refs/heads/' + ref), await candidate('refs/tags/' + ref)];
+    if (values.filter(Boolean).length > 1) fail('source.ambiguous-ref');
+  }
+  const value = values.find(Boolean);
+  if (!value || !oid(value)) fail('source.missing-ref');
+  if (oid(ref) && value !== ref) fail('source.not-commit');
+  return value;
+}
+export function parseListing(buffer) {
+  const text = utf8(buffer);
+  if (text && !text.endsWith('\0')) fail('source.tree-output');
+  return text.split('\0').filter(Boolean).map(line => {
+    const match = /^(\d{6}) (blob|tree|commit) ([a-f0-9]{40}|[a-f0-9]{64})\s+(\d+|-)\t([\s\S]+)$/.exec(line);
+    if (!match) fail('source.tree-output');
+    return { mode: match[1], type: match[2], oid: match[3], size: match[4] === '-' ? 0 : Number(match[4]), path: match[5] };
+  });
+}
+const runBoundedSourceGit = runGit;
+async function remoteRepo(source, options, preparation, runGit = runBoundedSourceGit) {
+  const repo = path.join(preparation, 'objects.git');
+  await mkdir(repo);
+  await runGit(repo, ['init', '--bare', '--template='], options);
+  const protocol = source.url.startsWith('https:') ? 'https' : 'ssh';
+  const transport = ['-c', 'protocol.allow=never', '-c', 'protocol.' + protocol + '.allow=always',
+    '-c', 'http.followRedirects=false'];
+  let wanted = source.ref;
+  if (!oid(wanted)) {
+    const refs = wanted === 'HEAD' || wanted.startsWith('refs/') ? [wanted] : ['refs/heads/' + wanted, 'refs/tags/' + wanted];
+    const listing = await runGit(repo, [...transport, 'ls-remote', '--', source.url, ...refs], { ...options, network: true });
+    const found = utf8(listing.bytes).trim().split('\n').filter(Boolean).map(l => l.split('\t')).filter(([, ref]) => refs.includes(ref));
+    if (found.length > 1) fail('source.ambiguous-ref');
+    if (found.length !== 1 || !oid(found[0][0])) fail('source.missing-ref');
+    wanted = found[0][0];
+  }
+  await runGit(repo, [...transport, '-c', 'fetch.unpackLimit=0', '-c', 'transfer.unpackLimit=0',
+    'fetch', '--depth=1', '--no-tags', '--no-recurse-submodules', '--no-auto-maintenance',
+    '--no-write-fetch-head', '--keep', '--', source.url, wanted],
+    { ...options, network: true, objects: path.join(repo, 'objects'), diagnoseUnadvertised: oid(source.ref) });
+  const resolved = await runGit(repo, ['rev-parse', '--verify', '--end-of-options', wanted + '^{commit}'], options);
+  const commit = utf8(resolved.bytes).trim();
+  if (!oid(commit)) fail('source.missing-ref');
+  if (oid(source.ref) && commit !== source.ref) fail('source.not-commit');
+  return { repo, commit };
+}
+// S7 repository preparation reuses bounded transport, not package validation.
+// Internal only: caller must keep tempRoot outside workspace/user repositories.
+// Failure retains the owned preparation path; never delete user data as rollback.
+export async function acquireRemoteRepository(source, { tempRoot, network = false, ...requestedBudget } = {}) {
+  validateSource(source);
+  if (source.transport !== 'remote' || source.subdirectory !== '.') fail('repository-source.kind');
+  if (network !== true) fail('source.network-required');
+  if (!path.isAbsolute(tempRoot ?? '')) fail('repository-source.temp-root');
+  const budget = repositoryBudget(requestedBudget);
+  let preparation;
+  const options = {...budget,deadline:performance.now()+budget.acquisitionMs};
+  try {
+    const parent = await realpath(tempRoot);
+    preparation = await mkdtemp(path.join(parent,'wpc-repository-'));
+    const {repo,commit} = await remoteRepo(source,options,preparation,runRepositoryGit);
+    await runRepositoryGit(repo,['fsck','--connectivity-only','--no-reflogs','--no-progress'],options);
+    return {source:structuredClone(source),resolvedSource:source.url,preparation,repo,commit,
+      ...budget,history:'shallow-depth-1',checkout:'not-performed',executionAuthorized:false};
+  } catch (cause) {
+    const error = cause instanceof ContractError ? cause : new ContractError('repository-source.io');
+    if (preparation) error.preparation=preparation;
+    throw error;
+  }
+}
+
+export async function acquire(source, { manifestBase, tempRoot = tmpdir(), network = false, packLimit = LIMITS.pack } = {}) {
+  validateSource(source);
+  cap(packLimit, LIMITS.pack, 'source.pack-limit');
+  if (!path.isAbsolute(manifestBase ?? '')) fail('source.manifest-base');
+  if (source.transport === 'remote' && !network) fail('source.network-required');
+  const deadline = performance.now() + LIMITS.acquisitionMs, options = { deadline, packLimit };
+  let preparation, snapshotPath;
+  try {
+  const parent = await realpath(tempRoot);
+  preparation = await mkdtemp(path.join(parent, 'wpc-git-'));
+  let repo, commit, resolvedSource;
+  if (source.transport === 'local') {
+    try { resolvedSource = await realpath(path.resolve(manifestBase, source.path)); }
+    catch (e) { fail(e.code === 'ENOENT' ? 'source.missing-repository' : 'source.repository-unavailable'); }
+    const local = await localRepo(resolvedSource, source.ref, preparation, options);
+    ({ repo, commit } = local);
+    options.alternate = local.alternate;
+  } else {
+    resolvedSource = source.url;
+    ({ repo, commit } = await remoteRepo(source, options, preparation));
+  }
+  const treeish = commit + ':' + (source.subdirectory === '.' ? '' : source.subdirectory);
+  const rootType = await runGit(repo, ['cat-file', '-t', treeish], options);
+  if (utf8(rootType.bytes).trim() !== 'tree') fail('source.package-root');
+  const listing = await runGit(repo, ['ls-tree', '-r', '-l', '-z', '--full-tree', treeish], options);
+  const verified = await verifyPackage(parseListing(listing.bytes), async entry => {
+    const r = await runGit(repo, ['cat-file', 'blob', entry.oid], { ...options, outputLimit: LIMITS.blob });
+    return r.bytes;
+  });
+  if (performance.now() > deadline) fail('source.timeout');
+  snapshotPath = await materialize(verified, parent);
+  if (performance.now() > deadline) fail('source.timeout');
+  return { source: structuredClone(source), resolvedSource, commit, preparation, snapshotPath,
+    manifest: verified.manifest, inventoryDigest: verified.inventoryDigest,
+    digest: verified.digest, fileHashes: verified.fileHashes, runtime: 'not-run' };
+  } catch (cause) {
+    const error = cause instanceof ContractError ? cause : new ContractError('source.io');
+    if (preparation) error.preparation = preparation;
+    if (snapshotPath) error.snapshotPath = snapshotPath;
+    throw error;
+  }
+}

package/src/source/inventory.js

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { parse, fail } from '../contracts/parse.js';
+import { validateStructure } from '../contracts/validate.js';
+import { portablePath, validateInventory, contractDigest } from '../contracts/semantic.js';
+import { requiredCapabilities } from '../providers/interface.js';
+
+export const LIMITS = Object.freeze({ files: 10000, blob: 8 * 1024 * 1024,
+  total: 128 * 1024 * 1024, manifest: 2 * 1024 * 1024, path: 240, segment: 100,
+  windowsPath: 240, posixPath: 1024, gitMs: 120000, acquisitionMs: 300000,
+  pack: 256 * 1024 * 1024, metadata: 4 * 1024 * 1024 });
+export const sha256 = bytes => 'sha256:' + createHash('sha256').update(bytes).digest('hex');
+export function cap(value, maximum, code) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > maximum) fail(code);
+}
+export function utf8(bytes) {
+  try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes); }
+  catch { fail('source.utf8'); }
+}
+export function checkEntries(entries) {
+  cap(entries.length, LIMITS.files, 'source.files');
+  let total = 0;
+  const names = new Map();
+  for (const e of entries) {
+    portablePath(e.path);
+    if (!['100644', '100755'].includes(e.mode) || e.type !== 'blob') fail('source.entry-type');
+    cap(e.size, LIMITS.blob, 'source.blob');
+    total += e.size; cap(total, LIMITS.total, 'source.total');
+    const parts = e.path.split('/');
+    for (let i = 1; i <= parts.length; i++) {
+      const spelling = parts.slice(0, i).join('/'), key = spelling.toLowerCase();
+      const kind = i === parts.length ? 'file' : 'directory';
+      const previous = names.get(key);
+      if (previous && (previous.spelling !== spelling || previous.kind !== kind || kind === 'file')) fail('source.collision');
+      names.set(key, { spelling, kind });
+    }
+  }
+  return total;
+}
+// Read only selected tree blobs, never a checked-out worktree or smudge filter.
+export async function verifyPackage(entries, readBlob) {
+  checkEntries(entries);
+  const manifestEntries = entries.filter(e => ['pipeline.json', 'pipeline.yaml', 'pipeline.yml'].includes(e.path));
+  if (manifestEntries.length !== 1) fail('source.manifest');
+  const buffers = new Map();
+  async function read(e, limit = LIMITS.blob) {
+    if (!e) fail('source.missing');
+    cap(e.size, limit, 'source.metadata-size');
+    if (buffers.has(e.path)) return buffers.get(e.path);
+    const bytes = await readBlob(e);
+    if (!Buffer.isBuffer(bytes) || bytes.length !== e.size) fail('source.blob-size');
+    if (bytes.subarray(0, 200).toString('ascii').startsWith('version https://git-lfs.github.com/spec/v1')) fail('source.lfs');
+    buffers.set(e.path, bytes); return bytes;
+  }
+  const manifestEntry = manifestEntries[0];
+  const manifestBytes = await read(manifestEntry, LIMITS.manifest);
+  const manifest = parse(utf8(manifestBytes), manifestEntry.path.endsWith('.json') ? 'json' : 'yaml');
+  validateStructure('pipeline', manifest);
+  portablePath(manifest.inventory); portablePath(manifest.resources);
+  if (manifest.inventory === manifestEntry.path) fail('inventory.self');
+  const inventoryBytes = await read(entries.find(e => e.path === manifest.inventory), LIMITS.manifest);
+  const inventory = parse(utf8(inventoryBytes), 'json');
+  validateInventory(inventory, { inventoryPath: manifest.inventory, manifestPath: manifestEntry.path });
+  const expected = new Set([...Object.keys(inventory), manifest.inventory]);
+  if (expected.size !== entries.length || entries.some(e => !expected.has(e.path))) fail('inventory.files');
+  for (const e of entries) {
+    const bytes = await read(e);
+    if (e.path !== manifest.inventory && sha256(bytes) !== inventory[e.path]) fail('inventory.hash');
+  }
+  function component(p, directory) {
+    portablePath(p);
+    if (directory ? !entries.some(e => e.path.startsWith(p + '/')) : !buffers.has(p)) fail('source.component');
+  }
+  component(manifest.resources, true);
+  for (const bundle of Object.values(manifest.bundles ?? {})) {
+    component(bundle.entry.source, false);
+    for (const id of bundle.providers) if (!Object.hasOwn(manifest.providers, id)) fail('bundle.provider-absent');
+  }
+  for (const decl of Object.values(manifest.providers)) {
+    requiredCapabilities(decl);
+    for (const key of ['skills', 'agents', 'mcp', 'entryInstructions'])
+      if (decl[key] !== null) component(decl[key], key === 'skills' || key === 'agents');
+  }
+  if (manifest.agentsDocument.mode === 'source') component(manifest.agentsDocument.path, false);
+  const fileHashes = Object.fromEntries([...buffers].map(([p, b]) => [p, sha256(b)]));
+  return { manifest, manifestPath: manifestEntry.path, inventoryDigest: sha256(inventoryBytes),
+    digest: contractDigest(fileHashes), files: buffers, fileHashes };
+}