@moretea-labs/forge 1.7.1 → 1.7.2

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable public Forge changes are recorded here. Release entries are tied to
 
 ## Unreleased
 
+## 1.7.2 - 2026-08-30
+
+### Runtime lifecycle reliability
+
+- Restart an already-active Linux/systemd Runtime after immutable package activation so the running process cannot remain fenced behind a newer release-authority revision.
+- Avoid duplicate systemd process-group shutdown signals from the package launcher, allowing controlled Runtime restarts to terminate cleanly.
+
+### Work and Controller authority
+
+- Promote effect Work to repository-change authority before governed source mutation and add narrowly fenced reconciliation for already-delivered historical effect Work.
+- Preserve authenticated explicit Controller session capability across MCP transport rotation while keeping same-principal conversations isolated.
+- Make the Windows worker-stderr path assertion platform-correct without changing production path behavior.
+
 ## 1.7.1 - 2026-08-30
 
 ### Runtime and lifecycle stabilization

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.7.1`.
+This inventory covers the direct runtime and development dependencies declared by `@moretea-labs/forge@1.7.2`.
 
 License values come from `package-lock.json` where available. For lock entries without a license field, the declared license was verified from package metadata during release preparation. This file is informational and does not replace the license text distributed by each dependency.
 

package/assets/skill-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.7.1",
-  "templateVersion": "1.7.1",
+  "version": "1.7.2",
+  "templateVersion": "1.7.2",
   "skillName": "forge",
   "contractId": "tasks-first-harness-v1",
   "compatibility": {

package/docs/operations/homebrew.md

@@ -6,8 +6,8 @@ Homebrew is planned as a convenience layer after the first stable npm/GitHub rel
 
 Do not publish a formula until all of the following are true:
 
-- `@moretea-labs/forge@1.7.1` exists on npm;
-- Git tag and GitHub Release `v1.7.1` exist and point to the tested commit;
+- `@moretea-labs/forge@1.7.2` exists on npm;
+- Git tag and GitHub Release `v1.7.2` exist and point to the tested commit;
 - the npm tarball has an immutable checksum;
 - macOS installation and `forge --version` / `forge doctor` tests pass;
 - upgrade and uninstall behavior is documented.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moretea-labs/forge",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "Local-first action assistant for software work with resumable execution, bounded tools, and reviewable evidence",
   "license": "MIT",
   "author": "Moretea Labs contributors",

package/src/cli/mcp/repository-tools.ts

@@ -5,6 +5,7 @@ import type { ResolvedExecutionIdentity } from '../../runtime/control-plane/exec
 import { assertNoBoundExecutionSessionMutation, resolveClaimedRepositoryWorkId, resolveExplicitClaimedRepositoryWork, type RepositoryWorkAttributionCaller } from '../../runtime/control-plane/execution/repository-work-attribution';
 import { getWorkContract } from '../../runtime/control-plane/facade/work-contract-store';
 import { assertWorkPathsWithinScope } from '../../runtime/control-plane/execution/work-path-scope';
+import { ensureRepositoryMutationWorkHandle } from '../../runtime/control-plane/execution/work-handle-authority';
 import { isTerminalWorkContractStatus } from '../../runtime/control-plane/facade/types';
 import { executeRepositoryCommand, previewRepositoryCommandExecution } from '../repositories/command-executor';
 import { withControllerLock } from '../repositories/locks';
@@ -990,18 +991,28 @@ export async function callRepositoryTool(
           controllerHome,
           { scope: 'repository', repoId: repository.repoId },
           'mcp:repository_safe_patch_apply',
-          () => applySafePatch(repository, {
-            sessionId: args.session_id,
-            purpose: args.purpose,
-            operations: args.operations,
-            chunkSize: args.chunk_size,
-            expectedRevision: args.expected_revision,
-            allowedPaths: args.allowed_paths,
-            continueOnError: args.continue_on_error,
-            refreshFingerprints: args.refresh_fingerprints,
-            recoverStaleSession: args.recover_stale_session,
-            binding,
-          }),
+          () => {
+            if (binding?.workId) {
+              ensureRepositoryMutationWorkHandle({
+                controllerHome,
+                repository,
+                workId: binding.workId,
+                principalId: binding.principalId ?? caller?.principalId ?? '',
+              });
+            }
+            return applySafePatch(repository, {
+              sessionId: args.session_id,
+              purpose: args.purpose,
+              operations: args.operations,
+              chunkSize: args.chunk_size,
+              expectedRevision: args.expected_revision,
+              allowedPaths: args.allowed_paths,
+              continueOnError: args.continue_on_error,
+              refreshFingerprints: args.refresh_fingerprints,
+              recoverStaleSession: args.recover_stale_session,
+              binding,
+            });
+          },
           60_000,
         );
         const changedFiles = [
@@ -1095,6 +1106,23 @@ export async function callRepositoryTool(
         if (deliveryWorkId) {
           throw new Error(`WORK_DELIVERY_REQUIRES_FINALIZE: ${deliveryWorkId} must pass Work verification and use rh_work finalize before default-branch integration`);
         }
+        if (executionIdentity.workId) {
+          const mutationClassification = classifyRepositoryCommand(args.command as string | string[], repository.defaultBranch);
+          if (mutationClassification.risk === 'workspace_write' || mutationClassification.risk === 'destructive') {
+            withControllerLock(
+              controllerHome,
+              { scope: 'repository', repoId: repository.repoId },
+              'mcp:repository_command_execute:mutation-authority',
+              () => ensureRepositoryMutationWorkHandle({
+                controllerHome,
+                repository,
+                workId: executionIdentity.workId!,
+                principalId: caller?.principalId ?? '',
+              }),
+              60_000,
+            );
+          }
+        }
         const timeoutMs = typeof args.timeout_ms === 'number'
           ? args.timeout_ms
           : typeof args.timeout_ms === 'string'

package/src/runtime/control-plane/execution/direct-edit-work-completion.ts

@@ -1,4 +1,6 @@
 import { createHash } from 'crypto';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
 import { getEditSession, listEditSessions, type EditSession } from '../../../cli/editing/edit-session';
 import { runProcess } from '../../../effects/process-runner';
 import { getWorkContract, updateWorkContract } from '../facade/work-contract-store';
@@ -184,6 +186,21 @@ function exactCommit(repoRoot: string, revision: string, label: string): string
   return result.stdout.trim();
 }
 
+function assertRemoteContainmentIfApplicable(repoRoot: string, targetBranch: string, targetRevision: string): void {
+  const remoteResult = git(repoRoot, ['config', '--get', `branch.${targetBranch}.remote`]);
+  const remote = remoteResult.ok ? remoteResult.stdout.trim() : '';
+  if (!remote || remote === '.') return;
+  const mergeResult = git(repoRoot, ['config', '--get', `branch.${targetBranch}.merge`]);
+  const mergeRef = mergeResult.ok ? mergeResult.stdout.trim() : '';
+  if (!mergeRef.startsWith('refs/heads/')) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_REMOTE_TRACKING_REQUIRED');
+  const remoteRef = `refs/remotes/${remote}/${mergeRef.slice('refs/heads/'.length)}`;
+  const remoteRevision = git(repoRoot, ['rev-parse', '--verify', `${remoteRef}^{commit}`]);
+  if (!remoteRevision.ok || !remoteRevision.stdout.trim()) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_REMOTE_TRACKING_REQUIRED');
+  if (!git(repoRoot, ['merge-base', '--is-ancestor', targetRevision, remoteRevision.stdout.trim()]).ok) {
+    throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_REMOTE_CONTAINMENT_REQUIRED');
+  }
+}
+
 function comparedRevisionPaths(repoRoot: string, baseRevision: string, targetRevision: string): string[] {
   const result = git(repoRoot, ['diff', '--name-only', '-z', baseRevision, targetRevision]);
   if (!result.ok) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_CHANGED_PATHS_UNAVAILABLE');
@@ -198,6 +215,20 @@ function normalizedComparedPaths(paths: string[]): string[] {
   return normalized;
 }
 
+function unresolvedRepositorySourcePaths(repoRoot: string): string[] {
+  const tracked = [
+    git(repoRoot, ['diff', '--name-only', '-z']),
+    git(repoRoot, ['diff', '--cached', '--name-only', '-z']),
+  ];
+  if (tracked.some((result) => !result.ok)) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_EFFECT_SOURCE_STATUS_UNAVAILABLE');
+  const untracked = git(repoRoot, ['ls-files', '--others', '--exclude-standard', '-z']);
+  if (!untracked.ok) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_EFFECT_SOURCE_STATUS_UNAVAILABLE');
+  return [...new Set([
+    ...tracked.flatMap((result) => result.stdout.split('\0').filter(Boolean)),
+    ...untracked.stdout.split('\0').filter((path) => path && !path.startsWith('.ai/harness/')),
+  ])].sort((left, right) => left.localeCompare(right));
+}
+
 /**
  * Explicitly close a historically delivered Direct Edit Work whose original
  * edit-session binding was missed. This is never inferred: the caller must
@@ -219,18 +250,24 @@ export function acceptReviewedDirectEditWorkReconciliation(input: ReviewedDirect
     }
     throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_WORK_TERMINAL: ${input.workId}`);
   }
-  const failedHandle = work.status === 'failed'
-    ? readWorkHandle(input.controllerHome, input.repoId, input.workId)
-    : undefined;
+  const currentHandle = readWorkHandle(input.controllerHome, input.repoId, input.workId);
+  const failedHandle = work.status === 'failed' ? currentHandle : undefined;
   const failedReviewedRecovery = work.workKind === 'repository_change'
     && work.status === 'failed'
     && failedHandle?.managedWorktree === false
     && failedHandle.state === 'failed'
     && failedHandle.finalization.validation === 'failed'
     && String(failedHandle.finalization.lastError ?? failedHandle.failureReason ?? '').includes('WORK_HANDLE_HEAD_CHANGED');
-  if ((isTerminalWorkContractStatus(work.status) && !failedReviewedRecovery) || work.workKind !== 'repository_change') {
+  const historicalEffectRecovery = !currentHandle
+    && !isTerminalWorkContractStatus(work.status)
+    && (work.workKind === 'local_effect' || work.workKind === 'remote_effect');
+  if ((isTerminalWorkContractStatus(work.status) && !failedReviewedRecovery)
+    || (work.workKind !== 'repository_change' && !historicalEffectRecovery)) {
     throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_WORK_NOT_ELIGIBLE: ${input.workId}`);
   }
+  if (historicalEffectRecovery && work.checks.length === 0) {
+    throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_CHECK_EVIDENCE_REQUIRED');
+  }
   if (!work.baseRevision?.trim()) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_BASE_REVISION_MISSING');
 
   const baseRevision = exactCommit(input.repoRoot, work.baseRevision, 'BASE_REVISION');
@@ -243,6 +280,7 @@ export function acceptReviewedDirectEditWorkReconciliation(input: ReviewedDirect
   if (!git(input.repoRoot, ['merge-base', '--is-ancestor', targetRevision, targetBranch]).ok) {
     throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_TARGET_UNREACHABLE');
   }
+  assertRemoteContainmentIfApplicable(input.repoRoot, targetBranch, targetRevision);
 
   const comparedPaths = normalizedComparedPaths(input.comparedPaths);
   let comparisonBaseRevision = baseRevision;
@@ -263,6 +301,15 @@ export function acceptReviewedDirectEditWorkReconciliation(input: ReviewedDirect
   });
   const dirty = git(input.repoRoot, ['status', '--porcelain=v1', '--', ...comparedPaths]);
   if (!dirty.ok || dirty.stdout.trim()) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_OWNED_PATHS_DIRTY');
+  if (historicalEffectRecovery) {
+    const separateOwnedWorktree = Boolean(work.worktreeRef?.trim())
+      && resolve(work.worktreeRef!) !== resolve(input.repoRoot)
+      && existsSync(work.worktreeRef!);
+    if (separateOwnedWorktree) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_EFFECT_CLEANUP_REQUIRED');
+    if (unresolvedRepositorySourcePaths(input.repoRoot).length > 0) {
+      throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_EFFECT_SOURCE_DELTA_UNRESOLVED');
+    }
+  }
 
   let verifiedAt = new Date().toISOString();
   for (const checkId of work.checks) {

package/src/runtime/control-plane/execution/work-handle-authority.ts

@@ -2,7 +2,9 @@ import { resolve } from 'path';
 import type { RepositoryRecord } from '../../../cli/repositories/types';
 import { resolveRepositorySelection, selectRepositoryCheckout } from '../../../cli/repositories/registry';
 import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
-import { getWorkContract } from '../facade/work-contract-store';
+import { getWorkContract, updateWorkContract } from '../facade/work-contract-store';
+import { controllerSessionPrincipalId, getControllerSession } from '../facade/controller-session-store';
+import { isTerminalWorkContractStatus } from '../facade/types';
 import { currentPermissionSnapshotVersion } from './validation';
 import { readWorkHandle, writeWorkHandle, type WorkHandleState } from './work-handle-store';
 
@@ -74,6 +76,58 @@ export function ensureRepositoryWorkHandle(input: {
   });
 }
 
+/**
+ * Upgrades an effect-only Work before the first governed repository mutation
+ * and materializes the existing repository delivery authority. The durable
+ * ControllerSession is the ownership source; the MCP transport session is not
+ * allowed to become a second mutation authority.
+ */
+export function ensureRepositoryMutationWorkHandle(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  principalId: string;
+}): { handle: WorkHandleState; promotedFrom?: 'local_effect' | 'remote_effect' } {
+  const store = { controllerHome: input.controllerHome, repoId: input.repository.repoId };
+  let contract = getWorkContract(store, input.workId);
+  if (!contract) throw new Error(`WORK_NOT_FOUND: ${input.workId}`);
+  if (isTerminalWorkContractStatus(contract.status) || contract.completionReceipt) {
+    throw new Error(`WORK_REPOSITORY_MUTATION_TERMINAL: ${input.workId}`);
+  }
+  const principalId = input.principalId.trim();
+  if (!principalId) throw new Error(`WORK_CONTROLLER_AUTHENTICATED_PRINCIPAL_REQUIRED: ${input.workId}`);
+  const owner = getControllerSession(store, input.workId);
+  if (!owner) throw new Error(`WORK_CONTROLLER_CLAIM_REQUIRED: ${input.workId}`);
+  if (controllerSessionPrincipalId(owner) !== principalId) {
+    throw new Error(`WORK_CONTROLLER_OWNERSHIP_MISMATCH: ${input.workId}`);
+  }
+
+  if (!contract.checkoutId) {
+    if (contract.worktreeRef?.trim()) {
+      throw new Error(`WORK_REPOSITORY_MUTATION_CHECKOUT_REQUIRED: ${input.workId}`);
+    }
+    contract = updateWorkContract(store, input.workId, { checkoutId: input.repository.activeCheckoutId });
+  }
+
+  let promotedFrom: 'local_effect' | 'remote_effect' | undefined;
+  if (contract.workKind === 'local_effect' || contract.workKind === 'remote_effect') {
+    promotedFrom = contract.workKind;
+    contract = updateWorkContract(store, input.workId, { workKind: 'repository_change' });
+  }
+  if (contract.workKind !== 'repository_change') {
+    throw new Error(`WORK_REPOSITORY_MUTATION_KIND_INVALID: ${input.workId}:${contract.workKind}`);
+  }
+
+  const handle = ensureRepositoryWorkHandle({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    workId: input.workId,
+    identity: { sessionId: owner.sessionId, principalId },
+  });
+  if (!handle) throw new Error(`WORK_REPOSITORY_MUTATION_HANDLE_REQUIRED: ${input.workId}`);
+  return { handle, ...(promotedFrom ? { promotedFrom } : {}) };
+}
+
 /**
  * Rebinds the durable WorkHandle to the Controller session that has already
  * been admitted by the ControllerSession authority. The compare-and-swap

package/src/runtime/gateway/mcp/runtime-tools.ts

@@ -1106,18 +1106,22 @@ function authenticatedFacadeControllerIdentity(
   options: { allowTransportSessionRollover?: boolean } = {},
 ): { controllerId: string; principalId: string; sessionId: string; controllerInstanceId: string; controllerType: 'chatgpt' | 'codex' | 'claude' | 'grok' | 'human' } {
   const principalId = ctx.principalId?.trim();
-  const sessionId = ctx.sessionId?.trim();
-  if (!principalId || !sessionId) {
-    throw new Error('CONTROLLER_AUTHENTICATED_SESSION_REQUIRED: reconnect or call session_start through the authenticated MCP transport');
-  }
+  const transportSessionId = ctx.sessionId?.trim();
   const requestedControllerId = typeof args.controller_id === 'string' ? args.controller_id.trim() : '';
   const requestedSessionId = typeof args.session_id === 'string' ? args.session_id.trim() : '';
+  if (!principalId || (!transportSessionId && !requestedSessionId)) {
+    throw new Error('CONTROLLER_AUTHENTICATED_SESSION_REQUIRED: reconnect or provide session_id through the authenticated MCP transport');
+  }
+  // The authenticated principal proves who is calling; session_id is the
+  // Controller-owned opaque lease capability that keeps one conversation/round
+  // stable across replaceable MCP transport sessions. Prefer that explicit
+  // capability whenever supplied. A foreign same-principal conversation still
+  // cannot rebind an existing Work unless it possesses the exact opaque session
+  // (or the stronger relay-round capability checked by the caller).
+  const sessionId = requestedSessionId || transportSessionId!;
   if (requestedControllerId && requestedControllerId !== principalId) {
     throw new Error('CONTROLLER_ID_CONTEXT_MISMATCH: controller_id must match the authenticated principal');
   }
-  if (!options.allowTransportSessionRollover && requestedSessionId && requestedSessionId !== sessionId) {
-    throw new Error('CONTROLLER_SESSION_CONTEXT_MISMATCH: session_id must match the authenticated MCP session');
-  }
   const requestedControllerType = typeof args.controller_type === 'string' && ['chatgpt', 'codex', 'claude', 'grok', 'human'].includes(args.controller_type)
     ? args.controller_type as 'chatgpt' | 'codex' | 'claude' | 'grok' | 'human'
     : undefined;

package/src/runtime/root/package-runtime-release.ts

@@ -156,7 +156,8 @@ function launcherSource(input: { packageRoot: string; indexPath: string; indexSh
     + `const loader=join(packageRoot,'src','runtime','shared','node-ts-loader.mjs');\n`
     + `const args=process.versions?.bun?[entry,...process.argv.slice(2)]:['--loader',loader,entry,...process.argv.slice(2)];\n`
     + `const child=spawn(process.execPath,args,{stdio:'inherit',env:process.env});\n`
-    + `for(const signal of ['SIGINT','SIGTERM','SIGHUP']){try{process.on(signal,()=>child.kill(signal));}catch{}}\n`
+    + `const managerSignalsProcessGroup=process.platform==='linux'&&Boolean(process.env.INVOCATION_ID);\n`
+    + `for(const signal of ['SIGINT','SIGTERM','SIGHUP']){try{process.on(signal,()=>{if(!managerSignalsProcessGroup)child.kill(signal);});}catch{}}\n`
     + `child.on('error',(error)=>{console.error('FORGE_PACKAGE_RUNTIME_LAUNCH_FAILED: '+error.message);process.exit(1);});\n`
     + `child.on('exit',(code)=>process.exit(code??1));\n`;
 }

package/src/runtime/root/package-runtime-service.ts

@@ -176,6 +176,20 @@ function cleanRuntimeInstallerEnvironment(env: NodeJS.ProcessEnv, releaseEnviron
   return { ...next, ...releaseEnvironment };
 }
 
+export function systemdRuntimeInstallCommands(unitName: string): string[][] {
+  // `enable --now` only starts an inactive unit. When Forge is already running,
+  // replacing the unit file and calling enable --now leaves the old ExecStart
+  // process alive even though release authority has advanced, fencing that
+  // process from writes. Enable and restart are intentionally separate so both
+  // first install and in-place immutable-release activation converge on the
+  // just-written unit while systemd remains the sole lifecycle owner.
+  return [
+    ['--user', 'daemon-reload'],
+    ['--user', 'enable', unitName],
+    ['--user', 'restart', unitName],
+  ];
+}
+
 function installSystemdUserService(controllerHome: string, env: NodeJS.ProcessEnv): string {
   const entrypoint = activeRuntimeEntrypoint(controllerHome);
   const launch = activeRuntimeLaunchSpec(controllerHome);
@@ -184,7 +198,7 @@ function installSystemdUserService(controllerHome: string, env: NodeJS.ProcessEn
   const unitName = `${label}.service`;
   const unitPath = join(env.HOME ?? homedir(), '.config', 'systemd', 'user', unitName);
   atomicWrite(unitPath, renderForgeRuntimeSystemdUserUnit({ executable: entrypoint, args: launch.args, environment: launch.environment }), 0o644);
-  for (const args of [['--user', 'daemon-reload'], ['--user', 'enable', '--now', unitName]]) {
+  for (const args of systemdRuntimeInstallCommands(unitName)) {
     const result = commandSucceeded('systemctl', args, env);
     if (result.status !== 0) throw new Error(`FORGE_RUNTIME_SYSTEMD_INSTALL_FAILED: systemctl ${args.join(' ')}: ${(result.stderr || result.stdout || '').trim()}`);
   }