repo-harness 0.16.1 → 0.16.2

package/README.es.md

@@ -467,8 +467,8 @@ repositorio adopte la misma política.
 
 ## Versión actual
 
-- Paquete npm: `repo-harness@0.16.1`
-- Sello de workflow generado: `repo-harness@0.16.1+template@0.16.1`
+- Paquete npm: `repo-harness@0.16.2`
+- Sello de workflow generado: `repo-harness@0.16.2+template@0.16.2`
 - Repositorio de GitHub: `Ancienttwo/repo-harness`
 - Notas de versión e historial: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -462,8 +462,8 @@ adopte la même policy.
 
 ## Release actuelle
 
-- Package npm : `repo-harness@0.16.1`
-- Generated workflow stamp : `repo-harness@0.16.1+template@0.16.1`
+- Package npm : `repo-harness@0.16.2`
+- Generated workflow stamp : `repo-harness@0.16.2+template@0.16.2`
 - Dépôt GitHub : `Ancienttwo/repo-harness`
 - Notes et historique de release : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -470,8 +470,8 @@ commit script や hooks に組み込まないでください。
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.16.1`
-- Generated workflow stamp：`repo-harness@0.16.1+template@0.16.1`
+- npm package：`repo-harness@0.16.2`
+- Generated workflow stamp：`repo-harness@0.16.2+template@0.16.2`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release notes and history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -450,8 +450,8 @@ repo-harness commit scripts or hooks unless that repo adopts the same policy.
 
 ## Current Release
 
-- npm package: `repo-harness@0.16.1`
-- Generated workflow stamp: `repo-harness@0.16.1+template@0.16.1`
+- npm package: `repo-harness@0.16.2`
+- Generated workflow stamp: `repo-harness@0.16.2+template@0.16.2`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release notes and history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.zh-CN.md

@@ -457,8 +457,8 @@ policy。
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.16.1`
-- Generated workflow stamp：`repo-harness@0.16.1+template@0.16.1`
+- npm package：`repo-harness@0.16.2`
+- Generated workflow stamp：`repo-harness@0.16.2+template@0.16.2`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release notes 和 history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/assets/partials/03-philosophy.partial.md

@@ -24,6 +24,12 @@ BUG_FIX_FLOW:
   3. Re-run full verification
 ```
 
+#### Artifact Hygiene
+
+- Write comments, commit messages, and PR text from the final diff only, as if discarded intermediate attempts never existed.
+- Comments state only the non-obvious reason at the owning boundary; never restate the operation, preserve intermediate attempts, or list speculative future work.
+- PR text states final behavior plus only the material rationale or trade-off a reviewer cannot recover from the diff; never mention never-merged states or reverted work.
+
 Detailed playbooks:
 - `docs/reference-configs/harness-overview.md`
 - `docs/reference-configs/agentic-development-flow.md`

package/assets/partials-agents/04-task-protocol.partial.md

@@ -53,7 +53,6 @@ RULES:
   - Promote factors only after hypothesis and backtest summary artifacts exist
   - Run the configured factor-lab check before claiming factor-lab work is complete
 {{/IF}}
-
 ACTIVE_PLAN:
   - .ai/harness/active-plan selects the current active plan only for its owning worktree; .ai/harness/active-worktree records that owner
 

package/assets/partials-agents/06-quality-safety.partial.md

@@ -12,6 +12,7 @@
 - Do not silently expand scope beyond approved plan.
 - If unexpected repo changes appear, stop and ask.
 - Prefer modifying existing files over unnecessary file creation.
+- Write comments, commit messages, and PR text from the final diff only: comments state only the non-obvious reason at the owning boundary; PR text states final behavior plus only rationale a reviewer cannot recover from the diff; never mention discarded attempts, reverted work, or never-merged states.
 
 ### Final Response Contract
 1. What changed — list modified files with one-line summary each

package/assets/reference-configs/global-working-rules.md

@@ -75,6 +75,14 @@ For architecture reviews, bug hunts, risky refactors, deployment issues, auth/pa
 
 Reports must be concise and grounded in files, commands, runtime behavior, observed code, or verified system state.
 
+## Artifact Hygiene
+
+Write comments, commit messages, and PR text from the final diff only, as if discarded intermediate attempts never existed. Session history is not documentation material.
+
+- Comments state only the non-obvious reason at the owning boundary; never restate the operation, preserve intermediate attempts, or list speculative future work.
+- PR text states final behavior plus only the material rationale or trade-off a reviewer cannot recover from the diff; never mention never-merged states, reverted work, or why something is absent (no "(without X)" titles, no paragraphs justifying a removal the reviewer never saw).
+- When the user rejects an addition, the correct artifact output is the version where that addition never existed — not an annotated explanation of its removal.
+
 ## Completion Summary Rule
 
 For non-trivial completed tasks, include a short `下一刀` section only when verified state shows a concrete next bottleneck, unresolved risk, failing check, deployment gap, review gap, or active-plan item that materially affects the user's stated goal.

package/assets/skill-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.16.1",
-  "templateVersion": "0.16.1",
+  "version": "0.16.2",
+  "templateVersion": "0.16.2",
   "skillName": "repo-harness",
   "contractId": "tasks-first-harness-v1",
   "compatibility": {
@@ -259,6 +259,10 @@
     {
       "version": "0.16.1",
       "description": "Replaces the boolean `overwrite` flag on the seven MCP workflow-artifact write tools with an optional `expected_sha256` revision precondition (absent = create-only with WOULD_OVERWRITE, supplied = guarded overwrite with REVISION_CONFLICT and no current-hash echo), routes those writes through a guarded synchronous writer with lstat symlink and regular-file guards plus temp+fsync+rename+parent-fsync, returns sha256/previousSha256 on success, and rejects undeclared parameters server-side with UNKNOWN_PARAMETER while `overwrite` specifically returns RETIRED_PARAMETER naming `expected_sha256`"
+    },
+    {
+      "version": "0.16.2",
+      "description": "Fixes MCP runtime issues from #204, binds MCP HTTP sessions to the startup profile with fail-closed config-flip handling, publishes the architecture queue lock owner record atomically via staged hard-link creation, requires and fail-closed-validates sandbox_mode in Codex custom-agent TOMLs with EXECUTION_BOUNDARY persona de-duplication, and adds artifact-hygiene rules (final-diff-only comments and PR text) to the global working rules and generated agent contracts"
     }
   ],
   "generatedProjectStamp": {

package/assets/templates/helpers/architecture-event.ts

@@ -3,6 +3,7 @@ import { createHash, randomUUID } from "crypto";
 import {
   closeSync,
   existsSync,
+  linkSync,
   lstatSync,
   mkdirSync,
   openSync,
@@ -520,18 +521,34 @@ function acquireQueueLock(requestsDir: string, ownerPid: number, ownerToken: str
   assertSafeWriteTarget(`${requestsDir}/.write-probe`);
   const lockFile = ".ai/harness/architecture/.architecture-queue.lock";
   assertSafeWriteTarget(lockFile);
+  const candidateToken = createHash("sha256").update(ownerToken).digest("hex").slice(0, 16);
+  const candidateFile = `${lockFile}.${ownerPid}.${candidateToken}.tmp`;
+  assertSafeWriteTarget(candidateFile);
   const deadline = Date.now() + 10_000;
   while (true) {
     try {
-      const fd = openSync(lockFile, "wx", 0o600);
+      const fd = openSync(candidateFile, "wx", 0o600);
       try {
         writeAllSync(fd, JSON.stringify({ pid: ownerPid, token: ownerToken, created_at: new Date().toISOString() }));
       } finally {
         closeSync(fd);
       }
-      return lockFile;
+      const holdBeforePublishMs = Number(process.env.REPO_HARNESS_ARCHITECTURE_HOLD_BEFORE_LOCK_PUBLISH_MS || "0");
+      if (Number.isFinite(holdBeforePublishMs) && holdBeforePublishMs > 0) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, holdBeforePublishMs);
+      }
+      try {
+        linkSync(candidateFile, lockFile);
+        return lockFile;
+      } catch (error: any) {
+        if (error?.code !== "EEXIST") throw error;
+      }
     } catch (error: any) {
-      if (error?.code !== "EEXIST" || !existsSync(lockFile)) throw error;
+      if (error?.code !== "EEXIST") throw error;
+    } finally {
+      rmSync(candidateFile, { force: true });
+    }
+    if (existsSync(lockFile)) {
       try {
         const owner = JSON.parse(readFileSync(lockFile, "utf8"));
         if (!processIsAlive(Number(owner.pid))) {
@@ -545,9 +562,9 @@ function acquireQueueLock(requestsDir: string, ownerPid: number, ownerToken: str
           continue;
         }
       }
-      if (Date.now() >= deadline) throw new Error(`architecture queue lock unavailable: ${lockFile}`);
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
     }
+    if (Date.now() >= deadline) throw new Error(`architecture queue lock unavailable: ${lockFile}`);
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
   }
 }
 

package/dist/hook-entry.js

@@ -14556,7 +14556,7 @@ function resolveReviewBaseRef(repoRoot) {
     return "HEAD";
   }
 }
-var BUNDLED_CLI_VERSION = "0.16.1".length > 0 ? "0.16.1" : null;
+var BUNDLED_CLI_VERSION = "0.16.2".length > 0 ? "0.16.2" : null;
 function providerCliVersion() {
   if (BUNDLED_CLI_VERSION !== null)
     return BUNDLED_CLI_VERSION;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-harness",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "Installs, migrates, audits, and repairs repo-local agentic development harnesses",
   "license": "MIT",
   "repository": {

package/scripts/architecture-event.ts

@@ -3,6 +3,7 @@ import { createHash, randomUUID } from "crypto";
 import {
   closeSync,
   existsSync,
+  linkSync,
   lstatSync,
   mkdirSync,
   openSync,
@@ -520,18 +521,34 @@ function acquireQueueLock(requestsDir: string, ownerPid: number, ownerToken: str
   assertSafeWriteTarget(`${requestsDir}/.write-probe`);
   const lockFile = ".ai/harness/architecture/.architecture-queue.lock";
   assertSafeWriteTarget(lockFile);
+  const candidateToken = createHash("sha256").update(ownerToken).digest("hex").slice(0, 16);
+  const candidateFile = `${lockFile}.${ownerPid}.${candidateToken}.tmp`;
+  assertSafeWriteTarget(candidateFile);
   const deadline = Date.now() + 10_000;
   while (true) {
     try {
-      const fd = openSync(lockFile, "wx", 0o600);
+      const fd = openSync(candidateFile, "wx", 0o600);
       try {
         writeAllSync(fd, JSON.stringify({ pid: ownerPid, token: ownerToken, created_at: new Date().toISOString() }));
       } finally {
         closeSync(fd);
       }
-      return lockFile;
+      const holdBeforePublishMs = Number(process.env.REPO_HARNESS_ARCHITECTURE_HOLD_BEFORE_LOCK_PUBLISH_MS || "0");
+      if (Number.isFinite(holdBeforePublishMs) && holdBeforePublishMs > 0) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, holdBeforePublishMs);
+      }
+      try {
+        linkSync(candidateFile, lockFile);
+        return lockFile;
+      } catch (error: any) {
+        if (error?.code !== "EEXIST") throw error;
+      }
     } catch (error: any) {
-      if (error?.code !== "EEXIST" || !existsSync(lockFile)) throw error;
+      if (error?.code !== "EEXIST") throw error;
+    } finally {
+      rmSync(candidateFile, { force: true });
+    }
+    if (existsSync(lockFile)) {
       try {
         const owner = JSON.parse(readFileSync(lockFile, "utf8"));
         if (!processIsAlive(Number(owner.pid))) {
@@ -545,9 +562,9 @@ function acquireQueueLock(requestsDir: string, ownerPid: number, ownerToken: str
           continue;
         }
       }
-      if (Date.now() >= deadline) throw new Error(`architecture queue lock unavailable: ${lockFile}`);
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
     }
+    if (Date.now() >= deadline) throw new Error(`architecture queue lock unavailable: ${lockFile}`);
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
   }
 }
 

package/src/cli/commands/mcp.ts

@@ -229,7 +229,10 @@ export function buildMcpCommand(): Command {
     .action((rawOpts: { json?: boolean }) => {
       void runMcpAction(() => {
         const rows = listManagedCodingWorkspaces();
-        console.log(rawOpts.json ? JSON.stringify({ workspaces: rows }, null, 2) : rows.map((row) => `${row.id}\t${row.branch}\t${row.dirty ? 'dirty' : 'clean'}\t${row.path_exists ? 'present' : 'missing'}`).join('\n'));
+        console.log(rawOpts.json ? JSON.stringify({ workspaces: rows }, null, 2) : rows.map((row) => {
+          const worktreeState = row.stale_reason !== null ? 'stale' : (row.dirty ? 'dirty' : 'clean');
+          return `${row.id}\t${row.branch}\t${worktreeState}\t${row.path_exists ? 'present' : 'missing'}`;
+        }).join('\n'));
       });
     });
   workspaces

package/src/cli/mcp/coding-workspaces.ts

@@ -611,23 +611,39 @@ export class CodingWorkspaceManager {
 
 export function listManagedCodingWorkspaces(env: NodeJS.ProcessEnv = process.env): Array<
   Omit<CodingWorkspace, 'root' | 'sourceRoot' | 'integrationTargetRef'>
-  & { integrationTargetRef: string | null; dirty: boolean; path_exists: boolean }
+  & { integrationTargetRef: string | null; dirty: boolean | null; path_exists: boolean; stale_reason: string | null }
 > {
-  return stateFile(env).workspaces.map((workspace) => ({
-    id: workspace.id,
-    repoId: workspace.repoId,
-    displayName: workspace.displayName,
-    mode: workspace.mode,
-    branch: workspace.branch,
-    baseRef: workspace.baseRef,
-    baseSha: workspace.baseSha,
-    integrationTargetRef: typeof workspace.integrationTargetRef === 'string' ? workspace.integrationTargetRef : null,
-    dirtySource: workspace.dirtySource,
-    openedAt: workspace.openedAt,
-    managed: workspace.managed,
-    path_exists: existsSync(workspace.root),
-    dirty: existsSync(workspace.root) ? isDirty(workspace.root) : false,
-  }));
+  return stateFile(env).workspaces.map((workspace) => {
+    const pathExists = existsSync(workspace.root);
+    // A recorded directory that still exists but is no longer a usable worktree
+    // is reported as one explicit stale row with an unknown dirty state. It is
+    // never skipped, never repaired, and never allowed to fail the whole list.
+    let dirty: boolean | null = pathExists ? null : false;
+    let staleReason: string | null = null;
+    if (pathExists) {
+      try {
+        dirty = isDirty(workspace.root);
+      } catch (error) {
+        staleReason = error instanceof Error ? error.message : String(error);
+      }
+    }
+    return {
+      id: workspace.id,
+      repoId: workspace.repoId,
+      displayName: workspace.displayName,
+      mode: workspace.mode,
+      branch: workspace.branch,
+      baseRef: workspace.baseRef,
+      baseSha: workspace.baseSha,
+      integrationTargetRef: typeof workspace.integrationTargetRef === 'string' ? workspace.integrationTargetRef : null,
+      dirtySource: workspace.dirtySource,
+      openedAt: workspace.openedAt,
+      managed: workspace.managed,
+      path_exists: pathExists,
+      dirty,
+      stale_reason: staleReason,
+    };
+  });
 }
 
 export function cleanupManagedCodingWorkspace(

package/src/cli/mcp/transports/http.ts

@@ -427,12 +427,17 @@ function acquireSession(sessions: McpSessionStore<McpHttpTransport>, sessionId:
   return sessions.acquire(sessionId);
 }
 
+export function resolveMcpHttpProfile(opts: McpServerOptions, config: ReturnType<typeof loadMcpLocalConfig>): string {
+  return opts.profile ?? config?.profile ?? 'planner';
+}
+
 async function handleMcpPost(
   req: Request,
   res: Response,
   opts: McpHttpOptions,
   sessions: McpSessionStore<McpHttpTransport>,
   codingRuntimes: CodingAuthorizationRuntimeStore | null,
+  startupProfile: string,
 ): Promise<void> {
   let body: unknown;
   try {
@@ -443,6 +448,22 @@ async function handleMcpPost(
   }
   const sessionId = sessionIdFromRequest(req);
   if (!sessionId && isInitializeRequest(body)) {
+    // The whole HTTP enforcement layer (coding-grant middleware, OAuth
+    // requirement, host/origin pinning, per-authorization coding runtimes) is
+    // decided once from the startup profile. A local config flip after startup
+    // would otherwise let a new session resolve a different tool context behind
+    // that stale enforcement, so sessions are bound to the startup profile and
+    // a flip fails closed until the operator restarts the server.
+    const currentProfile = resolveMcpHttpProfile(opts, loadMcpLocalConfig());
+    if (currentProfile !== startupProfile) {
+      res.status(503).json({
+        error: {
+          code: 'PROFILE_CHANGED',
+          message: `The local MCP profile changed from "${startupProfile}" to "${currentProfile}" after startup; restart the MCP server to serve the new profile.`,
+        },
+      });
+      return;
+    }
     const authorizationId = codingRuntimes ? authorizationIdFromRequest(req) : undefined;
     if (codingRuntimes && !authorizationId) {
       sendOAuthUnauthorized(req, res, 'Coding authorization identity is missing');
@@ -469,24 +490,28 @@ async function handleMcpPost(
       return;
     }
     let sessionInitialized = false;
-    const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: () => randomUUID(),
-      onsessioninitialized: (newSessionId) => {
-        reservation.commit(newSessionId, transport);
-        sessionInitialized = true;
-      },
-    }) as McpHttpTransport;
-    transport.authorizationId = authorizationId;
-    transport.onclose = () => {
-      if (transport.sessionId) sessions.delete(transport.sessionId);
-    };
-    const server = createRepoHarnessMcpServer({ ...opts, codingRuntime });
+    // Transport and server construction stay inside the try: a throw from either
+    // must still release the reservation, otherwise the slot leaks for the whole
+    // process lifetime and the store fails closed at capacity forever.
+    let transport: McpHttpTransport | undefined;
     try {
+      transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        onsessioninitialized: (newSessionId) => {
+          reservation.commit(newSessionId, transport as McpHttpTransport);
+          sessionInitialized = true;
+        },
+      }) as McpHttpTransport;
+      transport.authorizationId = authorizationId;
+      transport.onclose = () => {
+        if (transport?.sessionId) sessions.delete(transport.sessionId);
+      };
+      const server = createRepoHarnessMcpServer({ ...opts, profile: startupProfile, codingRuntime });
       await server.connect(transport);
       await transport.handleRequest(req, res, body);
     } finally {
       reservation.release();
-      if (!sessionInitialized) await transport.close().catch(() => undefined);
+      if (!sessionInitialized) await transport?.close().catch(() => undefined);
     }
     return;
   }
@@ -557,7 +582,7 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
   const repoRoot = resolveMcpRepoRoot(opts.repo ?? '.');
   assertNoLegacyRepoScopeMcpConfig(repoRoot);
   const localConfig = loadMcpLocalConfig();
-  const profile = opts.profile ?? localConfig?.profile ?? 'planner';
+  const profile = resolveMcpHttpProfile(opts, localConfig);
   const storedEndpoint = localConfig?.chatgpt?.endpoint;
   const storedPublicOrigin = storedEndpoint ? new URL(storedEndpoint).origin : undefined;
   const configuredPublicOrigin = process.env.REPO_HARNESS_MCP_PUBLIC_ORIGIN?.trim()
@@ -636,6 +661,16 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
     codingRuntimes?.cleanupExpired();
   }, Math.min(sessionTtlMs, 60_000));
   cleanupTimer.unref?.();
+  // The server description reported by /health is fixed for the process: this
+  // context is built once here instead of per request, where rebuilding it
+  // re-ran `git rev-parse --show-toplevel` synchronously and blocked the event
+  // loop for seconds on a cold disk. Live state stays live: the coding grant is
+  // still re-checked per request by the middleware above, and session counters
+  // are read from the store on each response.
+  const healthContext = createMcpToolContext({ ...opts, repo: repoRoot, codingRuntime: null });
+  const healthSchemaHash = createHash('sha256')
+    .update(JSON.stringify(buildMcpToolDefinitions(healthContext.policy, { enableChatgptBrowser: opts.enableChatgptBrowser === true })))
+    .digest('hex');
   const app = express();
 
   app.use((req, res, next) => {
@@ -678,16 +713,14 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
   app.get('/health', (req, res) => {
     sessions.cleanupExpired();
     codingRuntimes?.cleanupExpired();
-    const ctx = createMcpToolContext({ ...opts, repo: repoRoot, codingRuntime: null });
-    const tools = buildMcpToolDefinitions(ctx.policy, { enableChatgptBrowser: opts.enableChatgptBrowser === true });
     res.json({
       status: 'ok',
       server: 'repo-harness-mcp',
       package_version: repoHarnessPackageVersion(),
       mcp_protocol: 'streamable-http',
-      profile: ctx.policy.profile,
-      capabilities: ctx.policy.capabilities,
-      allowed_root_count: ctx.policy.allowedRoots?.length ?? 0,
+      profile: healthContext.policy.profile,
+      capabilities: healthContext.policy.capabilities,
+      allowed_root_count: healthContext.policy.allowedRoots?.length ?? 0,
       auth: authMode === 'oauth' ? (oauthPassphrase ? 'oauth' : 'missing') : (authToken ? authMode : 'missing'),
       auth_mode: authMode,
       public_origin: getPublicOrigin(req, configuredPublicOrigin),
@@ -698,7 +731,7 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
       sessions_closed: sessions.metrics.closed,
       sessions_expired: sessions.metrics.expired,
       sessions_evicted: sessions.metrics.evicted,
-      schema_hash: createHash('sha256').update(JSON.stringify(tools)).digest('hex'),
+      schema_hash: healthSchemaHash,
     });
   });
 
@@ -752,7 +785,7 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
   }
 
   app.post('/mcp', requireMcpHttpAuth(authMode, authToken, oauthProvider, configuredPublicOrigin), express.raw({ type: '*/*', limit: '1mb' }), (req, res) => {
-    handleMcpPost(req, res, { ...opts, repo: repoRoot }, sessions, codingRuntimes).catch((error: unknown) => {
+    handleMcpPost(req, res, { ...opts, repo: repoRoot }, sessions, codingRuntimes, profile).catch((error: unknown) => {
       if (!res.headersSent) res.status(500).json({ error: error instanceof Error ? error.message : String(error) });
     });
   });