wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28.md

@@ -521,6 +521,12 @@ Read/Fit result review remains fail-closed:
 - secrets for wallets, GitHub, model providers, Supabase service roles, or
   other systems may be passed into a sandbox only by explicit allowlist or
   brokered network policy; routine QA artifacts must show only redacted names.
+- pull-request delivery should normally use the reader's authenticated GitHub
+  App connection. For trusted local/staging harness QA, an operator token may be
+  supplied only by setting `BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK=1` and
+  explicitly forwarding `GITHUB_TOKEN` through the sandbox allowlist; VCS tools
+  must read that token from process environment without placing it in tool
+  inputs, artifact telemetry, or database stream rows.
 - `BITCODE_LLM_PROVIDER` and `BITCODE_LLM_MODEL` may pin the model path for
   reproducible generation; otherwise the runtime selects the available provider
   from credential posture, with OpenAI accepted when `OPENAI_API_KEY` is the

BITCODE_V28_QA.md

@@ -1155,9 +1155,21 @@ BITCODE_SANDBOX_SOURCE_COMMIT=31bbc0c5227b6b3aed5d107fd8507d35ec22970a \
 BITCODE_SANDBOX_SOURCE_REVISION=31bbc0c5227b6b3aed5d107fd8507d35ec22970a \
 BITCODE_SANDBOX_DEPOSIT_HAS_PROOF=1 \
 BITCODE_SANDBOX_DEPOSIT_HAS_MEASUREMENT=1 \
+BITCODE_ASSET_PACK_REAL_INFERENCE=1 \
+BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded \
+BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK=1 \
+BITCODE_SANDBOX_ENV_KEYS=SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY,OPENAI_API_KEY,BITCODE_ASSET_PACK_REAL_INFERENCE,BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE,BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS,GITHUB_TOKEN \
+BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS=600000 \
 pnpm run qa:pipeline-harness:sandbox
 ```
 
+`BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK=1` is only for trusted local/staging
+operator runs where the stored GitHub App installation token has expired and
+cannot be refreshed from app credentials. It lets VCS tools read `GITHUB_TOKEN`
+from process environment without adding the token to tool input payloads,
+artifact telemetry, or database stream rows. Product runtime should still use
+the authenticated user's GitHub App connection whenever possible.
+
 Before promotion, operators may add `BITCODE_SANDBOX_APPLY_LOCAL_PATCH=1` to
 overlay the current worktree on the cloned source revision. This is only for
 debugging the harness and pipeline implementation before deployment. Overlay
@@ -1185,7 +1197,8 @@ BITCODE_PIPELINE_STREAM_TO_DATABASE=1 \
 BITCODE_PIPELINE_STRUCTURED_DB=1 \
 BITCODE_ASSET_PACK_REAL_INFERENCE=1 \
 BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded \
-BITCODE_SANDBOX_ENV_KEYS=SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY,OPENAI_API_KEY,BITCODE_ASSET_PACK_REAL_INFERENCE,BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE,BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS
+BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK=1 \
+BITCODE_SANDBOX_ENV_KEYS=SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY,OPENAI_API_KEY,BITCODE_ASSET_PACK_REAL_INFERENCE,BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE,BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS,GITHUB_TOKEN
 ```
 
 These Supabase values must be real staging credentials. Placeholder hosts such

packages/generic-tools/vcs/__tests__/createOrUpdateFileTool.test.ts

@@ -51,6 +51,8 @@ const baseInput = {
 describe('createOrUpdateFileTool gating', () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    delete process.env.BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK;
+    delete process.env.GITHUB_TOKEN;
     (VCSConnections as jest.Mock).mockImplementation(() => mockConnectionManager);
     (VCSProviderFactory.create as jest.Mock).mockResolvedValue(mockProvider);
     mockConnectionManager.getConnectionById.mockResolvedValue({ id: 'conn-1' });
@@ -130,4 +132,29 @@ describe('createOrUpdateFileTool gating', () => {
       'abc123'
     );
   });
+
+  it('uses explicit environment delivery authority without loading a stored connection', async () => {
+    process.env.BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK = '1';
+    process.env.GITHUB_TOKEN = 'gh-test-token';
+
+    await createBranchTool.use({
+      provider: 'github',
+      owner: 'bitcode-labs',
+      repo: 'repo',
+      branch: 'feature/asset-pack',
+      from: 'abc123',
+    });
+
+    expect(VCSConnections).not.toHaveBeenCalled();
+    expect(mockProvider.createBranch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        provider: 'github',
+        accessToken: 'gh-test-token',
+      }),
+      'bitcode-labs',
+      'repo',
+      'feature/asset-pack',
+      'abc123'
+    );
+  });
 });

packages/generic-tools/vcs/src/index.ts

@@ -77,6 +77,11 @@ async function resolveConnectionContext(input: VcsInputBase): Promise<ResolvedCo
     throw new Error('VCS provider is required');
   }
 
+  const environmentAuth = resolveEnvironmentAuth(input.provider);
+  if (environmentAuth) {
+    return { auth: environmentAuth };
+  }
+
   const connectionManager = await createConnectionManager();
   let auth: VCSAuth | null = null;
   let instanceUrl: string | undefined;
@@ -100,6 +105,18 @@ async function resolveConnectionContext(input: VcsInputBase): Promise<ResolvedCo
   return { auth, instanceUrl };
 }
 
+function resolveEnvironmentAuth(provider: VCSProviderType): VCSAuth | null {
+  if (process.env.BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK !== '1') return null;
+  if (provider !== 'github') return null;
+
+  const accessToken =
+    process.env.GITHUB_TOKEN ||
+    process.env.GITHUB_PAT ||
+    process.env.GH_TOKEN;
+
+  return accessToken ? { provider, accessToken } : null;
+}
+
 function buildProviderConfig(
   provider: VCSProviderType,
   instanceUrl?: string,

packages/pipeline-hosts/README.md

@@ -86,6 +86,13 @@ trusted command environment. For local Vercel Sandbox creation, either pull
 token tuple `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`. Deployed
 Vercel code should use automatic OIDC rather than storing a Vercel token when
 possible.
+Pull-request delivery normally uses the authenticated user's stored GitHub App
+connection. GitHub installation tokens are short lived; if staging readback
+shows the stored token has expired and the local harness is intentionally using
+a trusted operator token, set `BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK=1` and pass
+`GITHUB_TOKEN` only through `BITCODE_SANDBOX_ENV_KEYS=GITHUB_TOKEN`. The VCS
+tools read that token from process environment and do not include it in tool
+inputs, artifact telemetry, or database stream rows.
 Staging-testnet Read/Fit QA must also set
 `BITCODE_ASSET_PACK_REAL_INFERENCE=1`. On the deployed streaming route,
 `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded` is the expected profile:
@@ -210,6 +217,8 @@ BITCODE_SANDBOX_DEPOSIT_HAS_PROOF=1 \
 BITCODE_SANDBOX_DEPOSIT_HAS_MEASUREMENT=1 \
 BITCODE_ASSET_PACK_REAL_INFERENCE=1 \
 BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded \
+BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK=1 \
+BITCODE_SANDBOX_ENV_KEYS=GITHUB_TOKEN \
 BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS=600000 \
 pnpm -C packages/pipeline-hosts run qa:asset-pack:sandbox
 ```

packages/pipeline-hosts/src/dev/run-asset-pack-sandbox-harness.ts

@@ -39,6 +39,7 @@ const TRUSTED_SANDBOX_ENV_KEYS = [
   'BITCODE_ASSET_PACK_READY_TO_INSTRUCT_USE_PTRR',
   'BITCODE_ASSET_PACK_VALIDATION_READY_TO_FINISH_USE_PTRR',
   'BITCODE_ASSET_PACK_FINISH_DELIVER_USE_PTRR',
+  'BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK',
   'BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS',
 ] as const;
 

packages/pipelines/asset-pack/src/__tests__/finish-delivery.test.ts

@@ -21,6 +21,8 @@ import deliverAssetPackToDestination from '../agents/finish/deliver-asset-pack-t
 describe('finish pull-request delivery', () => {
   beforeEach(() => {
     jest.resetAllMocks();
+    delete process.env.BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK;
+    delete process.env.GITHUB_TOKEN;
     createBranchUse.mockResolvedValue({ name: 'bitcode/asset-pack-run-123' });
     createOrUpdateFileUse.mockResolvedValue({ path: '.bitcode/asset-packs/run-123.md', content: 'written' });
     createPullRequestUse.mockResolvedValue({
@@ -118,11 +120,28 @@ describe('finish pull-request delivery', () => {
     const result = await deliverAssetPackToDestination({}, exec);
 
     expect(result.status).toBe('blocked_readiness');
-    expect(result.reason).toContain('GitHub connectionId or pipeline userId');
+    expect(result.reason).toContain('GitHub connectionId, pipeline userId, or explicit environment delivery authority');
     expect(createBranchUse).not.toHaveBeenCalled();
     expect(exec.get('finish', 'deliveryReadiness')).toMatchObject({
       status: 'blocked_readiness',
       prUrl: null,
     });
   });
+
+  it('allows explicit environment delivery authority without emitting token material', async () => {
+    process.env.BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK = '1';
+    process.env.GITHUB_TOKEN = 'gh-test-token';
+    const exec = execution();
+    exec.store('pipeline', 'userId', undefined);
+
+    const result = await deliverAssetPackToDestination({}, exec);
+
+    expect(result.status).toBe('delivered');
+    expect(createBranchUse).toHaveBeenCalledWith(expect.not.objectContaining({
+      accessToken: expect.anything(),
+      auth: expect.anything(),
+    }));
+    expect(exec.get('tools', 'vcs_create_branch:0').input).not.toHaveProperty('accessToken');
+    expect(emitToolUsage.mock.calls[0][2]).not.toHaveProperty('accessToken');
+  });
 });

packages/pipelines/asset-pack/src/agents/finish/deliver-asset-pack-to-destination-agent.ts

@@ -137,8 +137,8 @@ async function deliverPullRequest(
     return blockDelivery(execution, context, 'Pull-request delivery requires owner, repository, branch, and source commit.');
   }
 
-  if (!delivery.userId && !delivery.connectionId) {
-    return blockDelivery(execution, context, 'Pull-request delivery requires a GitHub connectionId or pipeline userId.');
+  if (!delivery.userId && !delivery.connectionId && !hasEnvironmentDeliveryAuth(repository.provider)) {
+    return blockDelivery(execution, context, 'Pull-request delivery requires a GitHub connectionId, pipeline userId, or explicit environment delivery authority.');
   }
 
   const common = {
@@ -234,6 +234,12 @@ async function deliverPullRequest(
   }
 }
 
+function hasEnvironmentDeliveryAuth(provider: string): boolean {
+  if (process.env.BITCODE_VCS_ALLOW_ENV_TOKEN_FALLBACK !== '1') return false;
+  if (provider !== 'github') return false;
+  return Boolean(process.env.GITHUB_TOKEN || process.env.GITHUB_PAT || process.env.GH_TOKEN);
+}
+
 function resolveRepositoryContext(input: any, execution: any) {
   const storedPipelineInput = findExecutionValue(execution, 'pipeline', 'input') || {};
   const sourceRevision =