@vantran-se/openchamber-web 2.1.1 → 2.2.0

package/server/lib/skills-catalog/cache.js

@@ -54,8 +54,9 @@ const scheduleDiskWrite = () => {
   }
 };
 
-export function getCacheKey({ normalizedRepo, subpath, identityId }) {
-  const safeRepo = String(normalizedRepo || '').trim();
+export function getCacheKey({ normalizedRepo, ref, subpath, identityId }) {
+  // Branches of one repository are different catalogs.
+  const safeRepo = `${String(normalizedRepo || '').trim()}${ref ? `#${ref}` : ''}`;
   const safeSubpath = String(subpath || '').trim();
   const safeIdentity = String(identityId || '').trim();
   return `${safeRepo}::${safeSubpath}::${safeIdentity}`;

package/server/lib/skills-catalog/curated-sources.js

@@ -1,3 +1,5 @@
+import { readEnterprisePolicy } from '../enterprise-mode.js';
+
 const CURATED_SKILLS_SOURCES = [
   {
     id: 'anthropic',
@@ -35,6 +37,8 @@ const CURATED_SKILLS_SOURCES = [
   },
 ];
 
-export function getCuratedSkillsSources() {
+/** The built-in catalogs, or none when the machine policy hides them. */
+export function getCuratedSkillsSources(policyOptions) {
+  if (readEnterprisePolicy(policyOptions).hideBuiltinSkillCatalogs) return [];
   return CURATED_SKILLS_SOURCES.slice();
 }

package/server/lib/skills-catalog/git.js

@@ -1,11 +1,44 @@
 import { execFile } from 'child_process';
+import { randomUUID } from 'node:crypto';
 import { promisify } from 'util';
+import { createGitCredentialBroker, GIT_CREDENTIAL_NONCE_ENV } from '../git/credential-broker.js';
+import { normalizeGitRemoteEndpoint } from '../git/credential-resolver.js';
+import { managedSshCommand } from '../git/network-operations.js';
 
 const execFileAsync = promisify(execFile);
 
 const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_MAX_BUFFER = 4 * 1024 * 1024;
 
+const isolatedGitEnvironment = (allowedProtocol) => {
+  const env = { ...process.env };
+  for (const name of Object.keys(env)) {
+    if (/^GIT_CONFIG(?:_|$)/i.test(name)
+      || /^GIT_TRACE(?:2)?(?:_|$)/i.test(name)
+      || /^(?:GIT_ASKPASS|SSH_ASKPASS|SSH_ASKPASS_REQUIRE|GIT_SSH|GIT_SSH_COMMAND|GIT_SSH_VARIANT|GIT_PROXY_COMMAND|SSH_AUTH_SOCK|HTTP_PROXY|HTTPS_PROXY|ALL_PROXY|NO_PROXY|http_proxy|https_proxy|all_proxy|no_proxy|NETRC|CURL_CA_BUNDLE|SSL_CERT_FILE|SSL_CERT_DIR)$/i.test(name)) {
+      delete env[name];
+    }
+    if (/^(?:GIT_CURL_VERBOSE|GIT_REDIRECT_STDERR|GIT_SSL_CERT|GIT_SSL_KEY|GIT_SSL_CAINFO|GIT_SSL_CAPATH|GIT_SSL_CIPHER_LIST|GIT_SSL_VERSION|GIT_SSL_NO_VERIFY|GIT_SSL_CERT_PASSWORD_PROTECTED|SSLKEYLOGFILE)$/i.test(name)
+      || /^CURL_/i.test(name)) {
+      delete env[name];
+    }
+  }
+  env.GIT_TERMINAL_PROMPT = '0';
+  env.GIT_CONFIG_NOSYSTEM = '1';
+  env.GIT_CONFIG_GLOBAL = process.platform === 'win32' ? 'NUL' : '/dev/null';
+  env.GIT_ALLOW_PROTOCOL = allowedProtocol;
+  if (allowedProtocol === 'https') {
+    // Git's Curl transport also consults netrc outside Git configuration; an
+    // ambient ~/.netrc entry must not authenticate as another account than
+    // the selected one. SSH keeps HOME for known_hosts.
+    for (const name of Object.keys(env)) {
+      if (['HOME', 'USERPROFILE', 'XDG_CONFIG_HOME', 'HOMEDRIVE', 'HOMEPATH'].includes(name.toUpperCase())) delete env[name];
+    }
+    env.HOME = env.USERPROFILE = env.XDG_CONFIG_HOME = process.platform === 'win32' ? 'NUL' : '/dev/null';
+  }
+  return env;
+};
+
 export function looksLikeAuthError(message) {
   const text = String(message || '');
   return (
@@ -13,6 +46,7 @@ export function looksLikeAuthError(message) {
     /publickey/i.test(text) ||
     /could not read from remote repository/i.test(text) ||
     /authentication failed/i.test(text) ||
+    /selected git identity/i.test(text) ||
     /fatal: could not/i.test(text)
   );
 }
@@ -25,23 +59,72 @@ export async function runGit(args, options = {}) {
   const identity = options.identity || null;
   const normalizedArgs = Array.isArray(args) ? args.slice() : [];
 
-  // Non-interactive git (avoid prompts / hangs)
-  const env = {
-    ...process.env,
-    GIT_TERMINAL_PROMPT: '0',
-  };
+  let env = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+  let credential;
+  let broker;
+  let lease;
 
-  if (identity?.sshKey) {
-    const sshKeyPath = String(identity.sshKey).trim();
-    if (sshKeyPath) {
-      // Avoid interactive host key prompts; still safe against changed keys.
-      const sshCommand = `ssh -i ${sshKeyPath} -o BatchMode=yes -o StrictHostKeyChecking=accept-new`;
-      normalizedArgs.unshift(`core.sshCommand=${sshCommand}`);
-      normalizedArgs.unshift('-c');
+  try {
+    if (identity?.credentialId) {
+      if (!options.credentialResolver || !identity.endpoint) {
+        return { ok: false, stdout: '', stderr: '', message: 'Selected Git identity is unavailable' };
+      }
+
+      const operationId = randomUUID();
+      try {
+        credential = await options.credentialResolver.resolve({
+          mode: 'managed',
+          credentialId: identity.credentialId,
+          endpoint: normalizeGitRemoteEndpoint(identity.endpoint),
+          operationId,
+          deadline: Date.now() + timeoutMs,
+        });
+      } catch {
+        return { ok: false, stdout: '', stderr: '', message: 'Authentication failed for the selected Git identity' };
+      }
+
+      if (credential.transport === 'https') {
+        broker = createGitCredentialBroker({ capacity: 1, ttlMs: timeoutMs });
+        await broker.start();
+        lease = broker.issue({ operationId, credential });
+        env = isolatedGitEnvironment('https');
+        env[GIT_CREDENTIAL_NONCE_ENV] = lease.env[GIT_CREDENTIAL_NONCE_ENV];
+        normalizedArgs.unshift(
+          '-c', 'credential.helper=',
+          '-c', 'credential.useHttpPath=true',
+          '-c', 'http.proxy=',
+          '-c', 'http.sslVerify=true',
+          '-c', 'http.followRedirects=false',
+          '-c', 'http.extraHeader=',
+          '-c', 'http.cookieFile=',
+          '-c', 'credential.interactive=false',
+          '-c', 'submodule.recurse=false',
+          '-c', 'fetch.recurseSubmodules=false',
+          ...lease.gitConfigArgs,
+        );
+      } else if (credential.transport === 'ssh') {
+        env = isolatedGitEnvironment('ssh');
+        normalizedArgs.unshift('-c', `core.sshCommand=${managedSshCommand(credential.key.privateKeyPath)}`);
+      } else {
+        return { ok: false, stdout: '', stderr: '', message: 'Selected Git identity cannot authenticate this repository' };
+      }
+    } else if (identity?.anonymous) {
+      env = isolatedGitEnvironment('https');
+      normalizedArgs.unshift(
+        '-c', 'credential.helper=',
+        '-c', 'http.proxy=',
+        '-c', 'http.followRedirects=false',
+        '-c', 'http.extraHeader=',
+        '-c', 'http.cookieFile=',
+        '-c', 'credential.interactive=false',
+        '-c', 'submodule.recurse=false',
+        '-c', 'fetch.recurseSubmodules=false',
+      );
+    } else if (identity) {
+      // A selected identity that names no credential never falls back to System Git.
+      return { ok: false, stdout: '', stderr: '', message: 'Selected Git identity is unavailable' };
     }
-  }
 
-  try {
     const { stdout, stderr } = await execFileAsync('git', normalizedArgs, {
       cwd,
       env,
@@ -52,19 +135,23 @@ export async function runGit(args, options = {}) {
 
     return { ok: true, stdout: stdout || '', stderr: stderr || '' };
   } catch (error) {
-    const err = error;
-    const stdout = typeof err?.stdout === 'string' ? err.stdout : '';
-    const stderr = typeof err?.stderr === 'string' ? err.stderr : '';
-    const message = err instanceof Error ? err.message : String(err);
+    const err = error instanceof Error ? error : new Error(String(error));
+    const stdout = String(err.stdout ?? '');
+    const stderr = String(err.stderr ?? '');
+    const message = err.message;
 
     return {
       ok: false,
       stdout,
       stderr,
       message,
-      code: typeof err?.code === 'number' ? err.code : null,
-      signal: typeof err?.signal === 'string' ? err.signal : null,
+      code: Number.isInteger(err.code) ? err.code : null,
+      signal: err.signal == null ? null : String(err.signal),
     };
+  } finally {
+    lease?.revoke();
+    if (credential?.transport === 'ssh') await credential.key.cleanup();
+    if (broker) await broker.close();
   }
 }
 

package/server/lib/skills-catalog/git.test.js

@@ -0,0 +1,78 @@
+import { describe, expect, it, vi } from 'vitest';
+import { runGit } from './git.js';
+
+const NULL_DEVICE = process.platform === 'win32' ? 'NUL' : '/dev/null';
+// A shell alias makes Git print the environment it runs under.
+const PRINT_HOME = ['-c', 'alias.print-home=!printf %s "$HOME"', 'print-home'];
+
+const httpsResolver = (password = 'catalog-private-token') => ({
+  resolve: vi.fn(async ({ endpoint }) => ({
+    mode: 'managed',
+    transport: 'https',
+    username: 'x-access-token',
+    password,
+    allowedEndpoint: endpoint,
+  })),
+});
+
+const httpsIdentity = {
+  credentialId: 'managed-account-reference',
+  endpoint: 'https://example.com/owner/private.git',
+};
+
+describe('skills catalog runGit', () => {
+  it('configures managed HTTPS Git through the broker without exposing the token', async () => {
+    const password = 'catalog-private-token';
+    const credentialResolver = httpsResolver(password);
+
+    const result = await runGit(['config', '--get', 'credential.helper'], { identity: httpsIdentity, credentialResolver });
+
+    expect(result.ok).toBe(true);
+    expect(result.stdout).toContain('credential-helper.js');
+    expect(result.stdout).not.toContain(password);
+    expect(result.stderr).not.toContain(password);
+    expect(credentialResolver.resolve).toHaveBeenCalledOnce();
+  });
+
+  it('runs managed SSH Git through the key wrapper and removes the key afterwards', async () => {
+    const cleanup = vi.fn(async () => {});
+    const credentialResolver = {
+      resolve: vi.fn(async () => ({
+        mode: 'managed',
+        transport: 'ssh',
+        key: { privateKeyPath: '/tmp/catalog-operation-key', cleanup },
+      })),
+    };
+
+    const result = await runGit(['config', '--get', 'core.sshCommand'], {
+      identity: { transport: 'ssh', credentialId: 'ssh-key-reference', endpoint: 'git@example.com:owner/private.git' },
+      credentialResolver,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.stdout).toContain('ssh-wrapper.js');
+    expect(result.stdout).toContain('/tmp/catalog-operation-key');
+    expect(cleanup).toHaveBeenCalledOnce();
+  });
+
+  it('hides the home directory from managed HTTPS Git so ~/.netrc cannot sign in', async () => {
+    const result = await runGit(PRINT_HOME, { identity: httpsIdentity, credentialResolver: httpsResolver() });
+
+    expect(result.ok).toBe(true);
+    expect(result.stdout).toBe(NULL_DEVICE);
+  });
+
+  it('hides the home directory from anonymous Git', async () => {
+    const result = await runGit(PRINT_HOME, { identity: { anonymous: true, transport: 'anonymous' } });
+
+    expect(result.ok).toBe(true);
+    expect(result.stdout).toBe(NULL_DEVICE);
+  });
+
+  it('refuses a selected identity without a credential instead of using System Git', async () => {
+    const result = await runGit(['--version'], { identity: { transport: 'ssh', endpoint: 'git@example.com:owner/private.git' } });
+
+    expect(result.ok).toBe(false);
+    expect(result.message).toBe('Selected Git identity is unavailable');
+  });
+});

package/server/lib/skills-catalog/install.js

@@ -90,14 +90,20 @@ async function copyDirectoryNoSymlinks(srcDir, dstDir) {
   await walk(srcDir, dstDir);
 }
 
-async function cloneRepo({ cloneUrl, identity, tempDir }) {
-  const preferred = ['clone', '--depth', '1', '--filter=blob:none', '--no-checkout', cloneUrl, tempDir];
-  const fallback = ['clone', '--depth', '1', '--no-checkout', cloneUrl, tempDir];
-
-  const result = await runGit(preferred, { identity, timeoutMs: 90_000 });
+async function cloneRepo({ cloneUrl, identity, credentialResolver, tempDir, ref = null }) {
+  // A `#ref` on the source picks the branch or tag; otherwise the default branch.
+  const branch = ref ? ['--branch', ref] : [];
+  const preferred = ['clone', '--depth', '1', '--filter=blob:none', '--no-checkout', ...branch, cloneUrl, tempDir];
+  const fallback = ['clone', '--depth', '1', '--no-checkout', ...branch, cloneUrl, tempDir];
+
+  const options = { identity, credentialResolver, timeoutMs: 90_000 };
+  const result = await runGit(preferred, options);
   if (result.ok) return { ok: true };
+  if (looksLikeAuthError(`${result.stderr || ''}\n${result.message || ''}`)) {
+    return { ok: false, error: result };
+  }
 
-  const fallbackResult = await runGit(fallback, { identity, timeoutMs: 90_000 });
+  const fallbackResult = await runGit(fallback, options);
   if (fallbackResult.ok) return { ok: true };
 
   return {
@@ -132,6 +138,7 @@ export async function installSkillsFromRepository({
   subpath,
   defaultSubpath,
   identity,
+  credentialResolver,
   scope,
   targetSource,
   workingDirectory,
@@ -174,7 +181,7 @@ export async function installSkillsFromRepository({
   const effectiveSubpath = parsed.effectiveSubpath || (typeof defaultSubpath === 'string' && defaultSubpath.trim() ? defaultSubpath.trim() : null);
   void effectiveSubpath;
 
-  const cloneUrl = identity?.sshKey ? parsed.cloneUrlSsh : parsed.cloneUrlHttps;
+  const cloneUrl = identity?.transport === 'ssh' ? parsed.cloneUrlSsh : parsed.cloneUrlHttps;
 
   const requestedDirs = Array.isArray(selections) ? selections.map((s) => String(s?.skillDir || '').trim()).filter(Boolean) : [];
   if (requestedDirs.length === 0) {
@@ -217,23 +224,25 @@ export async function installSkillsFromRepository({
   const tempBase = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'openchamber-skills-install-'));
 
   try {
-    const cloned = await cloneRepo({ cloneUrl, identity, tempDir: tempBase });
+    const cloned = await cloneRepo({ cloneUrl, identity, credentialResolver, tempDir: tempBase, ref: parsed.ref });
     if (!cloned.ok) {
       const msg = `${cloned.error?.stderr || ''}\n${cloned.error?.message || ''}`.trim();
       if (looksLikeAuthError(msg)) {
-        return { ok: false, error: { kind: 'authRequired', message: 'Authentication required to access this repository', sshOnly: true } };
+        return { ok: false, error: { kind: 'authRequired', message: 'Authentication required to access this repository' } };
       }
       return { ok: false, error: { kind: 'networkError', message: msg || 'Failed to clone repository' } };
     }
 
     // Selective checkout for only requested skill dirs.
-    await runGit(['-C', tempBase, 'sparse-checkout', 'init', '--cone'], { identity, timeoutMs: 15_000 });
-    const setResult = await runGit(['-C', tempBase, 'sparse-checkout', 'set', ...requestedDirs], { identity, timeoutMs: 30_000 });
+    await runGit(['-C', tempBase, 'sparse-checkout', 'init', '--cone'], { timeoutMs: 15_000 });
+    const setResult = await runGit(['-C', tempBase, 'sparse-checkout', 'set', ...requestedDirs], { timeoutMs: 30_000 });
     if (!setResult.ok) {
       return { ok: false, error: { kind: 'unknown', message: setResult.stderr || setResult.message || 'Failed to configure sparse checkout' } };
     }
 
-    const checkoutResult = await runGit(['-C', tempBase, 'checkout', '--force', 'HEAD'], { identity, timeoutMs: 60_000 });
+    // The checkout fetches the selected blobs from the partial clone, so it
+    // authenticates like the clone did.
+    const checkoutResult = await runGit(['-C', tempBase, 'checkout', '--force', 'HEAD'], { identity, credentialResolver, timeoutMs: 60_000 });
     if (!checkoutResult.ok) {
       return { ok: false, error: { kind: 'unknown', message: checkoutResult.stderr || checkoutResult.message || 'Failed to checkout repository' } };
     }

package/server/lib/skills-catalog/scan.js

@@ -45,14 +45,20 @@ async function safeRm(dir) {
   }
 }
 
-async function cloneRepo({ cloneUrl, identity, tempDir }) {
-  const preferred = ['clone', '--depth', '1', '--filter=blob:none', '--no-checkout', cloneUrl, tempDir];
-  const fallback = ['clone', '--depth', '1', '--no-checkout', cloneUrl, tempDir];
-
-  const result = await runGit(preferred, { identity, timeoutMs: 60_000 });
+async function cloneRepo({ cloneUrl, identity, credentialResolver, tempDir, ref = null }) {
+  // A `#ref` on the source picks the branch or tag; otherwise the default branch.
+  const branch = ref ? ['--branch', ref] : [];
+  const preferred = ['clone', '--depth', '1', '--filter=blob:none', '--no-checkout', ...branch, cloneUrl, tempDir];
+  const fallback = ['clone', '--depth', '1', '--no-checkout', ...branch, cloneUrl, tempDir];
+
+  const options = { identity, credentialResolver, timeoutMs: 60_000 };
+  const result = await runGit(preferred, options);
   if (result.ok) return { ok: true };
+  if (looksLikeAuthError(`${result.stderr || ''}\n${result.message || ''}`)) {
+    return { ok: false, error: result };
+  }
 
-  const fallbackResult = await runGit(fallback, { identity, timeoutMs: 60_000 });
+  const fallbackResult = await runGit(fallback, options);
   if (fallbackResult.ok) return { ok: true };
 
   return {
@@ -66,6 +72,7 @@ export async function scanSkillsRepository({
   subpath,
   defaultSubpath,
   identity,
+  credentialResolver,
 } = {}) {
   const gitCheck = await assertGitAvailable();
   if (!gitCheck.ok) {
@@ -78,16 +85,19 @@ export async function scanSkillsRepository({
   }
 
   const effectiveSubpath = parsed.effectiveSubpath || (typeof defaultSubpath === 'string' && defaultSubpath.trim() ? defaultSubpath.trim() : null);
-  const cloneUrl = identity?.sshKey ? parsed.cloneUrlSsh : parsed.cloneUrlHttps;
+  const cloneUrl = identity?.transport === 'ssh' ? parsed.cloneUrlSsh : parsed.cloneUrlHttps;
+  // Only commands that reach the remote get the identity: the clone, and the
+  // checkout or `show` that lazily fetch blobs from the partial clone.
+  const remoteGitOptions = { identity, credentialResolver };
 
   const tempBase = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'openchamber-skills-scan-'));
 
   try {
-    const cloned = await cloneRepo({ cloneUrl, identity, tempDir: tempBase });
+    const cloned = await cloneRepo({ cloneUrl, identity, credentialResolver, tempDir: tempBase, ref: parsed.ref });
     if (!cloned.ok) {
       const msg = `${cloned.error?.stderr || ''}\n${cloned.error?.message || ''}`.trim();
       if (looksLikeAuthError(msg)) {
-        return { ok: false, error: { kind: 'authRequired', message: 'Authentication required to access this repository', sshOnly: true } };
+        return { ok: false, error: { kind: 'authRequired', message: 'Authentication required to access this repository' } };
       }
       return { ok: false, error: { kind: 'networkError', message: msg || 'Failed to clone repository' } };
     }
@@ -102,13 +112,13 @@ export async function scanSkillsRepository({
 
     // Fast path: sparse checkout only SKILL.md files, then parse from disk.
     // This avoids one `git show` per skill.
-    const sparseInit = await runGit(['-C', tempBase, 'sparse-checkout', 'init', '--no-cone'], { identity, timeoutMs: 15_000 });
+    const sparseInit = await runGit(['-C', tempBase, 'sparse-checkout', 'init', '--no-cone'], { timeoutMs: 15_000 });
     if (sparseInit.ok) {
-      const sparseSet = await runGit(['-C', tempBase, 'sparse-checkout', 'set', ...patterns], { identity, timeoutMs: 30_000 });
+      const sparseSet = await runGit(['-C', tempBase, 'sparse-checkout', 'set', ...patterns], { timeoutMs: 30_000 });
       if (sparseSet.ok) {
-        const checkout = await runGit(['-C', tempBase, 'checkout', '--force', 'HEAD'], { identity, timeoutMs: 60_000 });
+        const checkout = await runGit(['-C', tempBase, 'checkout', '--force', 'HEAD'], { ...remoteGitOptions, timeoutMs: 60_000 });
         if (checkout.ok) {
-          const lsFiles = await runGit(['-C', tempBase, 'ls-files'], { identity, timeoutMs: 15_000 });
+          const lsFiles = await runGit(['-C', tempBase, 'ls-files'], { timeoutMs: 15_000 });
           if (lsFiles.ok) {
             skillMdPaths = lsFiles.stdout
               .split(/\r?\n/)
@@ -127,7 +137,7 @@ export async function scanSkillsRepository({
         listArgs.push('--', effectiveSubpath);
       }
 
-      const listResult = await runGit(listArgs, { identity, timeoutMs: 30_000 });
+      const listResult = await runGit(listArgs, { timeoutMs: 30_000 });
       if (!listResult.ok) {
         // If subpath doesn't exist, treat as empty scan.
         return {
@@ -172,7 +182,7 @@ export async function scanSkillsRepository({
         try {
           skillMdContent = await fs.promises.readFile(filePath, 'utf8');
         } catch {
-          const showResult = await runGit(['-C', tempBase, 'show', `HEAD:${skillMdPath}`], { identity, timeoutMs: 15_000 });
+          const showResult = await runGit(['-C', tempBase, 'show', `HEAD:${skillMdPath}`], { ...remoteGitOptions, timeoutMs: 15_000 });
           if (!showResult.ok) {
             warnings.push('Failed to read SKILL.md');
           } else {

package/server/lib/skills-catalog/source.js

@@ -11,8 +11,33 @@ function normalizeGitOwnerRepo(owner, repo) {
 }
 
 
+// A branch or tag after `#`: letters, digits and `._/-`, never starting with
+// `-` (it becomes a git argument) and never with `..`.
+const GIT_REF_PATTERN = /^(?!-)(?!.*\.\.)[A-Za-z0-9._/-]+$/;
+
+/**
+ * `owner/repo#ref`, `https://host/owner/repo.git#ref`: the source without the
+ * fragment, and the branch or tag it names (null when none).
+ */
+function splitSourceRef(source) {
+  const hashIndex = source.lastIndexOf('#');
+  if (hashIndex < 0) return { base: source, ref: null };
+  const ref = source.slice(hashIndex + 1).trim();
+  return { base: source.slice(0, hashIndex).trim(), ref: ref || null };
+}
+
 export function parseSkillRepoSource(input, options = {}) {
-  const raw = typeof input === 'string' ? input.trim() : '';
+  const parsed = parseSkillRepoBase(input, options);
+  if (!parsed.ok) return parsed;
+  const { ref } = splitSourceRef(typeof input === 'string' ? input.trim() : '');
+  if (ref !== null && !GIT_REF_PATTERN.test(ref)) {
+    return { ok: false, error: { kind: 'invalidSource', message: `Invalid branch or tag "${ref}"` } };
+  }
+  return { ...parsed, ref };
+}
+
+function parseSkillRepoBase(input, options) {
+  const raw = splitSourceRef(typeof input === 'string' ? input.trim() : '').base;
   if (!raw) {
     return { ok: false, error: { kind: 'invalidSource', message: 'Repository source is required' } };
   }

package/server/lib/skills-catalog/source.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseSkillRepoSource } from './source.js';
+
+describe('parseSkillRepoSource', () => {
+  it('reads a branch or tag after #, from shorthand and URLs', () => {
+    expect(parseSkillRepoSource('acme/skills#develop')).toMatchObject({ ok: true, normalizedRepo: 'acme/skills', ref: 'develop', effectiveSubpath: null });
+    expect(parseSkillRepoSource('acme/skills/pack#feature/v2')).toMatchObject({ ok: true, normalizedRepo: 'acme/skills', ref: 'feature/v2', effectiveSubpath: 'pack' });
+    expect(parseSkillRepoSource('https://github.com/acme/skills.git#v1.0.0')).toMatchObject({
+      ok: true,
+      cloneUrlHttps: 'https://github.com/acme/skills.git',
+      ref: 'v1.0.0',
+    });
+    expect(parseSkillRepoSource('git@gitlab.acme.dev:team/skills.git#beta')).toMatchObject({ ok: true, host: 'gitlab.acme.dev', ref: 'beta' });
+  });
+
+  it('has no ref without #, or with an empty one', () => {
+    expect(parseSkillRepoSource('acme/skills').ref).toBeNull();
+    expect(parseSkillRepoSource('acme/skills#').ref).toBeNull();
+  });
+
+  it('refuses a ref git would read as an option or a range', () => {
+    for (const source of ['acme/skills#--upload-pack=x', 'acme/skills#a..b', 'acme/skills#x y']) {
+      expect(parseSkillRepoSource(source), source).toMatchObject({ ok: false, error: { kind: 'invalidSource' } });
+    }
+  });
+});

package/server/lib/source-control/DOCUMENTATION.md

@@ -17,13 +17,14 @@ Repository bindings intentionally keep provider accounts, parent Git transport c
 - `binding-contract.js` owns the dependency-free strict persisted binding parser, separate binding-response parser, readiness projection, aggregate state, and public endpoint validation for the server and the web adapter. The persisted parser rejects response-only credential presentation, so `source-control-bindings.json` remains references-only. The response parser accepts only the tagged safe presentation contract and rejects unknown fields. Safe endpoint metadata accepts credential-free HTTP/HTTPS, SSH URL, and SCP display forms plus bounded base64url fingerprints; local-file, credential-bearing HTTPS, query, fragment, traversal, control-character, and unsafe fingerprint forms fail closed. Each provider stores its approved fetch endpoint and readiness. Each remote stores readiness alongside its exact fetch/push endpoints; auxiliary grants have their own readiness. Only `ready` grants authority. `account-unavailable`, `confirmation-required`, and `config-changed` retain repair metadata without granting the affected capability. Binding `state` is an aggregate UI summary, never the authority gate.
 - `mutation-storage.js` owns strict versioned persistence for bounded source-control mutation records in `source-control-mutations.json` under the server config root. `claim` persists an idempotency key before provider work, exact key-and-digest replays return the stored record, and digest changes report a conflict. `complete` permits one transition from `running` to a terminal state. Failed records may retain only an HTTP status and stable code for replay; messages and provider payloads are rejected. Terminal records have a seven-day retention by default and may be evicted oldest-first at capacity; `running` and `outcome-unknown` records are never pruned or evicted. Snapshots use serialized atomic mode-`0600` writes and reject unknown fields, provider payloads, private text, tokens, and raw URLs.
 - `mutation-executor.js` canonicalizes and hashes mutation input, joins exact process-local duplicates, claims persisted state before provider work, and never retries a provider mutation. Provider routes include the exact resolved credential account ID and revision in this digest and keep the credential account ID in durable replay authority. They pass the verified provider-user ID separately for receipt actor metadata and audit `providerAccountId`; clients cannot supply it. Its store must provide `withExecutionLock(key, operation)`, scoped to that store's file path and the SHA-256 digest of the key, not the input digest. The executor holds this separate lock from before claim through provider work or reconciliation and mutation/audit completion. A second daemon waits or fails busy, never reconciles live work. Completed requests replay their compact receipt after acquiring the lock. An unlocked persisted `running` record enters provider reconciliation; a crashed owner's leftover lock is reclaimed by the next contender (see below). Ambiguous provider outcomes become sticky `outcome-unknown` records when persistence remains available. A failed completion write leaves the prior snapshot available for reconciliation, never another provider write.
-- `audit-storage.js` owns the separate version-1 `source-control-audit.json` log under `OPENCHAMBER_DATA_DIR`. It does not share records, retention, or write sequencing with mutation replay storage. The strict schema stores one logical record per provider mutation idempotency key and per server Git operation ID. It accepts only `user` as the current initiator, the `provider-api` or `openchamber-server-git` executor, an immutable runtime and repository snapshot, an authoritative provider-user account ID or `null`, authoritative transport metadata, a compact redacted target, lifecycle timestamps, and a result state, stable error code, and bounded steps. An opaque credential ID is never substituted for provider identity. Provider API records require a `null` transport reference. Single-path Git records require either an exact opaque managed `credentialId` or a system marker. Sync records keep exact fetch and push references separately, including mixed system and managed transport. Checkout hydration records a bounded list of discovered auxiliary kinds and endpoint fingerprints plus only the exact server-validated transport reference for each granted endpoint; it records `null` transport when no transfer grant is used and always records a `null` provider account. Existing hydration records with the former single parent transport remain readable but new records never write that attribution. The schema rejects unknown fields and URL-shaped transport or target values, so raw endpoints, hydration paths, directories, key paths, credential payloads, process output, provider payloads, and free-form errors cannot enter the file. GitLab account IDs retain their authoritative normalized-instance prefix because that prefix is part of the account identifier, not a transport endpoint. Writes are serialized, atomic, and mode `0600`. Resolved terminal records expire after 30 days by default and are oldest-first capacity candidates; `planned`, `running`, and `outcome-unknown` records are never pruned or evicted.
+- `audit-storage.js` owns the separate version-1 `source-control-audit.json` log under `OPENCHAMBER_DATA_DIR`. It does not share records, retention, or write sequencing with mutation replay storage. The strict schema stores one logical record per provider mutation idempotency key and per server Git operation ID. It accepts only `user` as the current initiator, the `provider-api` or `openchamber-server-git` executor, an immutable runtime and repository snapshot, an authoritative provider-user account ID or `null`, authoritative transport metadata, a compact redacted target, lifecycle timestamps, and a result state, stable error code, and bounded steps. An opaque credential ID is never substituted for provider identity. Provider API records require a `null` transport reference and a change-request target, or an issue target for `issue-comment`. Single-path Git records require either an exact opaque managed `credentialId` or a system marker. Sync records keep exact fetch and push references separately, including mixed system and managed transport. Checkout hydration records a bounded list of discovered auxiliary kinds and endpoint fingerprints plus only the exact server-validated transport reference for each granted endpoint; it records `null` transport when no transfer grant is used and always records a `null` provider account. Existing hydration records with the former single parent transport remain readable but new records never write that attribution. The schema rejects unknown fields and URL-shaped transport or target values, so raw endpoints, hydration paths, directories, key paths, credential payloads, process output, provider payloads, and free-form errors cannot enter the file. GitLab account IDs retain their authoritative normalized-instance prefix because that prefix is part of the account identifier, not a transport endpoint. Writes are serialized, atomic, and mode `0600`. Resolved terminal records expire after 30 days by default and are oldest-first capacity candidates; `planned`, `running`, and `outcome-unknown` records are never pruned or evicted.
 - `mutation-executor.js` also drives provider audit lifecycle around the existing durable claim. Exact in-process duplicates and durable replays use `provider:<idempotencyKey>` and therefore reuse the same audit record, while `transportReference` remains `null` because provider API calls do not use Git transport. The executor rejects an audited execution before claim when the route omits verified provider identity. Two credentials for the same provider user therefore share actor identity in receipts and audits, but their exact credential and binding authority still produce different mutation digests. Audit persistence does not replace or relax mutation claim, digest conflict, reconciliation, sticky unknown-outcome, or replay behavior.
 
 Provider replay and reconciliation after restart reuse the runtime snapshot from the existing audit record. Strict audit planning still checks the other immutable fields. Terminal replay does not rewrite audit history. An unfinished audit can complete from the durable mutation receipt without repeating provider work.
 - `binding-service.js` accepts remote names and account/credential references, normalizes provider instances before uniqueness checks and persistence, then resolves endpoint metadata and provider repository coordinates from current server-side Git state. A provider instance must match the selected remote host and applicable HTTP port; supplied repository coordinates must equal the path-derived coordinates. Client-provided URLs are never authoritative. Provider reads check the binding revision, the bound provider's own readiness and that its primary remote still exists, so a remote added or removed beside it does not interrupt change-request status. A repository with no binding (revision 0) or whose binding names no account for a host is read with the account the client is signed in to on that host, as before bindings existed: the context must name a remote that really points at the instance, and whether the account exists is the provider route's to decide. Mutation contexts pass the same checks plus the binding's saved config revision, then validate an idempotency key and an exact, copied target shape before provider code receives them. Stale revision or config/remote errors carry the current authoritative repository, revision, and redacted binding record. Account reconciliation uses the same normalization and also matches equivalent instance spellings in previously stored records.
 - `url-redaction.js` removes URL credentials, query data, and fragments from endpoint display URLs before repository context crosses the server boundary. Endpoint fingerprints remain derived from normalized transport authority rather than the shortened display, so hidden query or fragment changes still change authority.
 - `status-cache.js` keeps the last-known change request status per exact trusted read context (instance, account, credential revision, repository, binding revision, directory, branch, remote), bounded and TTL-fresh. A provider route answers a fresh repeat from it, answers a transient provider failure with the last-known status, drops a repository's entries after a mutation and an account's entries after invalidation. GitLab uses it; GitHub keeps its own equivalent in `github/routes.js` for now.
+- `change-request-worktree.js` builds a change-request source from a directory and a pull or merge request number alone, for `session.create` with `pullRequest`. It chooses the read context the way the client's `getBoundSourceControlReadContexts` and `useGitHubReadContext` do: a ready bound provider first, else a remote on GitHub or a known GitLab instance read with that host's current account (each provider's `readCurrentAccountId`, the gh or glab login only while the user switched to it), GitHub before GitLab. The provider's `readChangeRequestHead` then answers the project, head branch, head revision and head owner on that context's primary remote; a GitHub pull request whose fork was deleted, or a number that is not one there, is refused with its own message. No caller-supplied project, endpoint or remote name enters the result, and the Git contributor pipeline resolves it again before any transfer.
 - `oauth-flow-registry.js` keeps device-flow secrets in a bounded, process-local registry. Clients receive an opaque flow ID; completion acquires the matching provider and normalized instance exclusively, then releases retryable attempts or consumes terminal attempts. Restarting the server invalidates every outstanding flow.
 
 ## Cross-process locks and recovery

package/server/lib/source-control/audit-storage.js

@@ -1,3 +1,4 @@
+import { isPlainObject, isString } from '../shared/guards.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -16,7 +17,11 @@ const GIT_OPERATIONS = new Set([
 ]);
 const PROVIDER_OPERATIONS = new Set([
   'change-request-create', 'change-request-update', 'change-request-merge', 'change-request-ready',
+  'change-request-comment', 'change-request-review', 'issue-comment', 'change-request-state', 'issue-state',
+  'change-request-labels', 'issue-labels', 'change-request-reviewers',
 ]);
+// What a provider write acts on: `issue-*` names an issue, everything else a change request.
+const providerTargetKind = (operation) => (operation.startsWith('issue-') ? 'issue' : 'change-request');
 const RESULT_STEPS = new Set([
   'validated', 'authenticated', 'transferred', 'updated-local-repository', 'checked-out', 'cleaned-up',
   'fetch:succeeded', 'fetch:skipped', 'fetch:conflicted', 'fetch:failed', 'fetch:cancelled',
@@ -26,10 +31,6 @@ const RESULT_STEPS = new Set([
 ]);
 
 const emptyState = () => ({ version: VERSION, records: {} });
-const isPlainObject = (value) => value === Object(value)
-  && !Array.isArray(value)
-  && Object.getPrototypeOf(value) === Object.prototype;
-const isString = (value) => Object.prototype.toString.call(value) === '[object String]';
 const hasExactKeys = (value, required, optional = []) => {
   const keys = Object.keys(value);
   return required.every((key) => keys.includes(key))
@@ -113,8 +114,8 @@ const isGitTarget = (value) => isPlainObject(value)
     && isSafeText(value.destination.displayName) && isSafeText(value.destination.fingerprint, 1024)));
 const isProviderTarget = (value) => isPlainObject(value)
   && hasExactKeys(value, ['kind', 'operation', 'projectId'], ['number', 'head', 'base', 'headSha'])
-  && value.kind === 'change-request'
   && PROVIDER_OPERATIONS.has(value.operation)
+  && value.kind === providerTargetKind(value.operation)
   && isSafeText(value.projectId, 1024)
   && (value.number === undefined || isPositiveInteger(value.number))
   && (value.head === undefined || isSafeText(value.head, 1024))
@@ -150,7 +151,7 @@ const isRecord = (value, id) => {
     || !EXECUTORS.has(value.executorKind) || !isRuntime(value.runtime)
     || !isNullableText(value.repositoryId) || !isNullableAccountId(value.providerAccountId)
     || !isTransportReference(value.transportReference) || !isTarget(value.target)
-    || (value.executorKind === 'provider-api' && (value.transportReference !== null || value.target.kind !== 'change-request'))
+    || (value.executorKind === 'provider-api' && (value.transportReference !== null || !isProviderTarget(value.target)))
     || (value.executorKind === 'openchamber-server-git' && (value.target.kind !== 'git-network'
       || !hydrationTransportMatchesTarget(value.transportReference, value.target)))
     || (value.target.kind === 'git-network' && value.target.operation === 'checkout-hydration'

package/server/lib/source-control/audit-storage.test.js

@@ -53,6 +53,17 @@ describe('source-control audit storage', () => {
     expect(results.find((result) => !result.ok).error.code).toBe('SOURCE_CONTROL_AUDIT_CONFLICT');
   });
 
+  it('names an issue comment by its issue and refuses an issue target for other writes', async () => {
+    const { store } = await setup();
+    const issueTarget = { kind: 'issue', operation: 'issue-comment', projectId: 'project_one', number: 3 };
+    await expect(store.plan(plan('issue', { target: issueTarget }))).resolves.toBeTruthy();
+    await expect(store.plan(plan('review', { target: { kind: 'change-request', operation: 'change-request-review', projectId: 'project_one', number: 7 } })))
+      .resolves.toBeTruthy();
+    await expect(store.plan(plan('issue-state', { target: { ...issueTarget, operation: 'issue-state' } }))).resolves.toBeTruthy();
+    await expect(store.plan(plan('mismatch', { target: { ...issueTarget, operation: 'change-request-comment' } }))).rejects.toThrow();
+    await expect(store.plan(plan('mismatch-two', { target: { ...issueTarget, kind: 'change-request' } }))).rejects.toThrow();
+  });
+
   it('fails closed on busy reads and cleans failed snapshot writes', async () => {
     const { filePath, store } = await setup();
     await store.plan(plan('original'));

package/server/lib/source-control/binding-service.js

@@ -1,3 +1,4 @@
+import { isPlainObject, isString } from '../shared/guards.js';
 import { normalizeSourceControlProviderInstance } from './provider-instance.js';
 import { resolvePrivateRepositoryIdentity } from './repository-identity.js';
 import { fingerprintRemoteUrl, redactRemoteUrl } from './url-redaction.js';
@@ -11,10 +12,6 @@ const bindingInputError = (message) => {
   return error;
 };
 
-const isPlainObject = (value) => value === Object(value)
-  && !Array.isArray(value)
-  && Object.getPrototypeOf(value) === Object.prototype;
-const isString = (value) => Object.prototype.toString.call(value) === '[object String]';
 const safePresentationText = (value, maximum = 512) => isString(value) && value.length > 0
   && value.length <= maximum && value.trim() === value && !/[\0\r\n]/.test(value);
 const safeProviderUsername = (value) => safePresentationText(value, 255) && /^[A-Za-z0-9_.-]+$/.test(value);
@@ -272,7 +269,7 @@ const normalizeProviderInstance = (provider, instance, makeError = bindingInputE
 };
 
 /** The host a remote address or a provider instance points at, lowercased; null when it names none. */
-const hostOf = (value) => {
+export const hostOf = (value) => {
   const text = String(value ?? '').trim();
   if (!text) return null;
   try { return new URL(text.includes('://') ? text : `https://${text}`).hostname.toLowerCase() || null; }