@awak-app/simy-cli 0.7.28 → 0.7.31

package/src/session-supervision/claude-desktop-archive.js

@@ -0,0 +1,57 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { createClaudeDesktopNativeAdapter } from './claude-desktop-native.js';
+import { resolveClaudeDesktopTarget } from './claude-desktop-target.js';
+
+const failure = (code, message) => Object.assign(new Error(message), { code });
+const sameIdentity = (a, b) => ['desktopId', 'session', 'cwd', 'partition'].every(key => a[key] === b[key]);
+
+// One native Desktop window is shared by all conversations. Serialize operations
+// across identities; a per-session queue would allow one operation to navigate
+// away from the other operation's target.
+export function createClaudeDesktopArchiveController({
+  readTarget = resolveClaudeDesktopTarget,
+  native = createClaudeDesktopNativeAdapter(),
+  wait = delay,
+  attempts = 60,
+  interval = 250,
+} = {}) {
+  if (!Number.isInteger(attempts) || attempts < 1 || attempts > 120 || !Number.isFinite(interval) || interval < 0 || interval > 5000)
+    throw new TypeError('Invalid Claude Desktop readback bounds.');
+  let queue = Promise.resolve();
+  return function setArchived(candidate, archived, { signal, beforeDispatch = async () => {} } = {}) {
+    // Copy the caller's selection before queueing: later catalog refreshes must
+    // not redirect an already requested native operation.
+    const selection = { provider: candidate?.provider, session: candidate?.session, cwd: candidate?.cwd };
+    const run = async () => {
+      if (typeof archived !== 'boolean') throw new TypeError('Expected an explicit archive state.');
+      signal?.throwIfAborted();
+      const original = await readTarget(selection);
+      if (original.archived === archived) return { state: 'verified', archived, changed: false };
+      if (!native?.setArchived) throw failure('claude_desktop_unavailable', 'Native Claude Desktop archive control is unavailable on this host.');
+      await beforeDispatch();
+      signal?.throwIfAborted();
+      const current = await readTarget(selection);
+      if (!sameIdentity(original, current)) throw failure('claude_desktop_identity_changed', 'Claude Desktop conversation identity changed.');
+      if (current.archived === archived) return { state: 'verified', archived, changed: false };
+      // Dispatch at most once. A timeout may mean the provider applied the
+      // operation; reconcile its own state rather than blindly clicking again.
+      let dispatchError;
+      try { await native.setArchived(current, archived, { signal }); }
+      catch (error) { dispatchError = error; }
+      const deadline = Date.now() + 15_000;
+      for (let index = 0; index < attempts; index++) {
+        const observed = await readTarget(selection);
+        if (!sameIdentity(original, observed)) throw failure('claude_desktop_identity_changed', 'Claude Desktop conversation identity changed during native control.');
+        if (observed.archived === archived) return { state: 'verified', archived, changed: true };
+        signal?.throwIfAborted();
+        if (dispatchError?.mutationPossible === false || Date.now() >= deadline) break;
+        if (index + 1 < attempts) await wait(interval, undefined, { signal });
+      }
+      if (dispatchError) throw dispatchError;
+      throw failure('claude_desktop_state_unconfirmed', 'Claude Desktop has not confirmed the requested archive state. Refresh before retrying.');
+    };
+    const result = queue.then(run);
+    queue = result.catch(() => {});
+    return result;
+  };
+}

package/src/session-supervision/claude-desktop-native.js

@@ -0,0 +1,50 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+const execute = promisify(execFile);
+const script = fileURLToPath(new URL('./claude-desktop-native.jxa.js', import.meta.url));
+const failure = (code, message) => Object.assign(new Error(message), { code });
+
+export function createClaudeDesktopNativeAdapter({ platform = process.platform, run = execute } = {}) {
+  async function invoke(request, { signal } = {}) {
+    if (platform !== 'darwin') throw failure('claude_desktop_platform_unsupported', 'Claude Desktop native archive control currently requires a macOS conversation host.');
+    signal?.throwIfAborted();
+    let stdout;
+    try {
+      ({ stdout } = await run('/usr/bin/osascript', ['-l', 'JavaScript', script, JSON.stringify(request)], {
+        encoding: 'utf8', timeout: ['inspect', 'preflight'].includes(request.operation) ? 5000 : 20_000, maxBuffer: 32_768, killSignal: 'SIGKILL', signal,
+      }));
+    } catch (error) {
+      signal?.throwIfAborted();
+      throw failure('claude_desktop_native_unconfirmed', 'Claude Desktop did not return a result. Refresh its archive state before retrying.');
+    }
+    let response;
+    try { response = JSON.parse(stdout); } catch { throw failure('claude_desktop_native_unconfirmed', 'Claude Desktop returned an unreadable result.'); }
+    if (response?.ok !== true) {
+      const code = /^claude_desktop_[a-z_]+$/.test(response?.code || '') ? response.code : 'claude_desktop_ui_unavailable';
+      throw Object.assign(failure(code, typeof response?.message === 'string' && response.message.length <= 1000 ? response.message : 'Claude Desktop native control is unavailable.'), { mutationPossible: response.mutationPossible !== false });
+    }
+    return response.data;
+  }
+  return {
+    inspect: options => invoke({ operation: 'inspect' }, options),
+    setup: options => invoke({ operation: 'setup' }, options),
+    async setArchived(target, archived, options) {
+      if (typeof archived !== 'boolean') throw new TypeError('An explicit archive state is required.');
+      if (!/^local_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(target?.desktopId || '')) throw failure('claude_desktop_identity_unverified', 'An exact Claude Desktop identity is required.');
+      const readiness = await invoke({ operation: 'inspect' }, options);
+      if (readiness?.available !== true) throw failure('claude_desktop_accessibility_required', 'Enable Accessibility for the app running SIMY on the conversation host, then retry.');
+      const preflight = await invoke({ operation: 'preflight' }, options);
+      if (preflight?.safeToNavigate !== true) throw Object.assign(failure('claude_desktop_ui_unavailable', 'Claude Desktop navigation safety could not be confirmed.'), { mutationPossible: false });
+      try { await run('/usr/bin/open', ['-b', 'com.anthropic.claudefordesktop', 'claude://claude.ai/epitaxy/' + target.desktopId], {
+        encoding: 'utf8', timeout: 5000, maxBuffer: 4096, killSignal: 'SIGKILL', signal: options?.signal,
+      }); } catch {
+        options?.signal?.throwIfAborted();
+        throw Object.assign(failure('claude_desktop_ui_unavailable', 'Claude Desktop could not open the selected conversation. Open its Code tab and retry.'), { mutationPossible: false });
+      }
+      const result = await invoke({ operation: archived ? 'archive' : 'restore', desktopId: target.desktopId, title: target.title }, options);
+      if (result?.dispatched !== true) throw failure('claude_desktop_native_unconfirmed', 'Claude Desktop did not confirm dispatch.');
+      return result;
+    },
+  };
+}

package/src/session-supervision/claude-desktop-native.jxa.js

@@ -0,0 +1,195 @@
+// macOS system JavaScript for Automation. No compiler, developer mode, private
+// provider file writes, or embedded credentials are required on the user's Mac.
+ObjC.import('AppKit');
+ObjC.import('ApplicationServices');
+ObjC.bindFunction('AXUIElementCreateApplication', ['id', ['int']]);
+ObjC.bindFunction('AXUIElementCreateSystemWide', ['id', []]);
+ObjC.bindFunction('AXUIElementCopyAttributeValue', ['int', ['id', 'id', 'id *']]);
+ObjC.bindFunction('AXUIElementCopyElementAtPosition', ['int', ['id', 'float', 'float', 'id *']]);
+ObjC.bindFunction('AXValueGetValue', ['bool', ['id', 'int', 'void *']]);
+ObjC.bindFunction('AXIsProcessTrustedWithOptions', ['bool', ['id']]);
+ObjC.bindFunction('AXUIElementPerformAction', ['int', ['id', 'id']]);
+ObjC.bindFunction('AXUIElementSetAttributeValue', ['int', ['id', 'id', 'id']]);
+ObjC.bindFunction('CFEqual', ['bool', ['id', 'id']]);
+
+function pause(seconds) { $.NSRunLoop.currentRunLoop.runUntilDate($.NSDate.dateWithTimeIntervalSinceNow(seconds)); }
+function failure(code, message) { var error = new Error(message); error.code = code; throw error; }
+function attribute(element, name, requireReadable) {
+  var result = Ref(), status = $.AXUIElementCopyAttributeValue(element, $(name), result);
+  // A leaf may omit optional children. Transport/stale-element errors do not
+  // prove that a subtree is empty and must not allow navigation past drafts.
+  if (requireReadable && status !== 0 && status !== Number($.kAXErrorAttributeUnsupported) && status !== Number($.kAXErrorNoValue))
+    failure('claude_desktop_ui_unavailable', 'Claude Desktop accessibility content could not be inspected.');
+  return status === 0 ? result[0] : null;
+}
+function textAttribute(element, name) {
+  var value = attribute(element, name);
+  return value ? (name === 'AXURL' ? String(ObjC.unwrap(value.absoluteString)) : String(ObjC.unwrap(value))) : '';
+}
+function descendants(root, predicate) {
+  var result = [], count = 0;
+  function visit(element, depth) {
+    if (++count > 12000 || depth > 55) failure('claude_desktop_ui_unavailable', 'Claude Desktop accessibility tree exceeded its supported bounds.');
+    if (predicate(element)) result.push(element);
+    var children = attribute(element, 'AXChildren', true);
+    if (children) ObjC.unwrap(children).forEach(function(child) { visit(child, depth + 1); });
+  }
+  visit(root, 0); return result;
+}
+function hasAncestor(element, predicate) {
+  for (var index = 0; index < 60 && element; index++, element = attribute(element, 'AXParent')) if (predicate(element)) return true;
+  return false;
+}
+// AXValue stores two CGFloat doubles on supported 64-bit Macs. Foundation owns
+// the full 16-byte output buffer; do not write a CGPoint into an untyped Ref.
+function geometry(element, name, type) {
+  var data = $.NSMutableData.dataWithLength(16), value = attribute(element, name);
+  if (!value || !$.AXValueGetValue(value, type, data.mutableBytes)) failure('claude_desktop_ui_unavailable', 'Claude control geometry is unavailable.');
+  var encoded = String(ObjC.unwrap(data.base64EncodedStringWithOptions(0)));
+  var alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/', bytes = [], bits = 0, accumulated = 0;
+  for (var index = 0; index < encoded.length; index++) {
+    var digit = alphabet.indexOf(encoded[index]); if (digit < 0) break;
+    accumulated = (accumulated << 6) | digit; bits += 6;
+    if (bits >= 8) { bits -= 8; bytes.push((accumulated >> bits) & 255); }
+  }
+  if (bytes.length !== 16) failure('claude_desktop_ui_unavailable', 'Invalid Claude control geometry.');
+  var view = new DataView(new Uint8Array(bytes).buffer);
+  return [view.getFloat64(0, true), view.getFloat64(8, true)];
+}
+function ensureNoActiveWork(root) {
+  descendants(root, function(element) {
+    var role = textAttribute(element, 'AXRole');
+    if (!role) failure('claude_desktop_ui_unavailable', 'Claude Desktop element identity could not be inspected.');
+    if (['AXSheet', 'AXDialog'].indexOf(role) >= 0 || textAttribute(element, 'AXSubrole') === 'AXDialog')
+      failure('claude_desktop_ui_changed', 'Close the Claude Desktop dialog before changing conversations.');
+    if (role === 'AXButton' && ['Stop', 'Stop response', 'Stop generating', '停止', '応答を停止', '生成を停止'].indexOf(textAttribute(element, 'AXTitle') || textAttribute(element, 'AXDescription')) >= 0)
+      failure('claude_desktop_running', 'Claude Desktop is generating a response. Wait before changing conversations.');
+    if (['AXTextArea', 'AXTextField', 'AXComboBox'].indexOf(role) >= 0) {
+      var value = attribute(element, 'AXValue');
+      if (value === null) failure('claude_desktop_ui_unavailable', 'Claude Desktop input state could not be inspected.');
+      if (String(ObjC.unwrap(value)).trim()) failure('claude_desktop_unsaved_input', 'Claude Desktop contains unsent input. Preserve it before changing conversations.');
+    }
+    return false;
+  });
+}
+function perform(input) {
+  if (!input || ['inspect', 'setup', 'preflight', 'archive', 'restore'].indexOf(input.operation) < 0) failure('claude_desktop_invalid_request', 'Invalid Claude Desktop operation.');
+  var bundle = 'com.anthropic.claudefordesktop', workspace = $.NSWorkspace.sharedWorkspace;
+  var appURL = workspace.URLForApplicationWithBundleIdentifier(bundle);
+  if (!appURL || appURL.isNil()) failure('claude_desktop_not_installed', 'Install Claude Desktop on the conversation host and sign in to its Code tab.');
+  var version = String(ObjC.unwrap($.NSBundle.bundleWithURL(appURL).objectForInfoDictionaryKey('CFBundleShortVersionString')));
+  if (input.operation === 'setup') {
+    $.AXIsProcessTrustedWithOptions($({ AXTrustedCheckOptionPrompt: true }));
+    // Open the real OS setting. Never grant accessibility or change TCC records.
+    workspace.openURL($.NSURL.URLWithString('x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'));
+  }
+  var trusted = Boolean($.AXIsProcessTrusted());
+  if (['inspect', 'setup'].indexOf(input.operation) >= 0) return { available: trusted, version: version, code: trusted ? 'ready' : 'claude_desktop_accessibility_required' };
+  if (!trusted) failure('claude_desktop_accessibility_required', 'Enable Accessibility for the app running SIMY in macOS System Settings, then retry. Run simy sessions provider-setup --provider claude on this host to open the setting.');
+  if (input.operation === 'preflight') {
+    var existingApps = ObjC.unwrap($.NSRunningApplication.runningApplicationsWithBundleIdentifier(bundle));
+    if (existingApps.length === 0) return { safeToNavigate: true };
+    if (existingApps.length !== 1) failure('claude_desktop_ui_unavailable', 'Claude Desktop application identity is ambiguous.');
+    var existingAX = $.AXUIElementCreateApplication(existingApps[0].processIdentifier);
+    // Electron may initially expose only its window chrome. Request its AX
+    // tree without navigating or granting any OS permission, then wait briefly
+    // for content. Unsupported attributes are harmless; actual reads decide.
+    $.AXUIElementSetAttributeValue(existingAX, $('AXManualAccessibility'), $(true));
+    for (var attempt = 0; attempt < 11; attempt++) {
+      var windows = attribute(existingAX, 'AXWindows', true);
+      if (!windows || ObjC.unwrap(windows).length === 0) failure('claude_desktop_ui_unavailable', 'Claude Desktop windows could not be inspected before navigation.');
+      var ready = true;
+      ObjC.unwrap(windows).forEach(function(window) {
+        ensureNoActiveWork(window);
+        if (descendants(window, function(element) { return textAttribute(element, 'AXRole') === 'AXWebArea'; }).length === 0) ready = false;
+      });
+      if (ready) return { safeToNavigate: true };
+      if (attempt < 10) pause(0.2);
+    }
+    failure('claude_desktop_ui_unavailable', 'Claude Desktop conversation content could not be inspected before navigation.');
+  }
+  if (!/^local_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(input.desktopId || '') || typeof input.title !== 'string' || !input.title.trim() || input.title.length > 512)
+    failure('claude_desktop_invalid_request', 'An exact Claude Desktop conversation is required.');
+  var apps = ObjC.unwrap($.NSRunningApplication.runningApplicationsWithBundleIdentifier(bundle));
+  if (apps.length === 0) {
+    workspace.openURL(appURL);
+    for (var launch = 0; launch < 30 && apps.length === 0; launch++) { pause(0.2); apps = ObjC.unwrap($.NSRunningApplication.runningApplicationsWithBundleIdentifier(bundle)); }
+  }
+  if (apps.length !== 1) failure('claude_desktop_ui_unavailable', 'Open a single Claude Desktop application and retry.');
+  var running = apps[0], app = $.AXUIElementCreateApplication(running.processIdentifier);
+  // The resume/import deep link may change archive state. Use navigation only.
+  // The parent opens the navigation URL through LaunchServices before invoking us.
+  // LaunchServices already activates the deep-linked window; let its AX tree
+  // settle without issuing another application activation.
+  pause(0.2);
+  function targetArea() {
+    var matches = descendants(app, function(element) {
+      return textAttribute(element, 'AXRole') === 'AXWebArea' && ['https://claude.ai/epitaxy/' + input.desktopId, 'https://claude.ai/code/' + input.desktopId].indexOf(textAttribute(element, 'AXURL')) >= 0;
+    });
+    if (matches.length !== 1) failure('claude_desktop_ui_unavailable', 'The exact Claude Desktop conversation is not uniquely visible. Open its Code tab and retry.');
+    return matches[0];
+  }
+  function ensureActionTarget(element) {
+    var currentArea = targetArea();
+    if (!running.active) failure('claude_desktop_ui_changed', 'Claude Desktop lost focus before the operation. Retry when it is visible.');
+    if (!hasAncestor(element, function(parent) { return $.CFEqual(parent, currentArea); }))
+      failure('claude_desktop_ui_changed', 'The selected Claude control no longer belongs to the requested conversation. Refresh before retrying.');
+  }
+  function click(element) {
+    ensureActionTarget(element);
+    var position = geometry(element, 'AXPosition', 1), size = geometry(element, 'AXSize', 2);
+    var x = position[0] + size[0] / 2, y = position[1] + size[1] / 2, hit = Ref();
+    if (!isFinite(x) || !isFinite(y) || size[0] <= 0 || size[1] <= 0) failure('claude_desktop_ui_unavailable', 'Claude control is not visible.');
+    var status = $.AXUIElementCopyElementAtPosition($.AXUIElementCreateSystemWide(), x, y, hit);
+    if (status !== 0 || !hasAncestor(hit[0], function(parent) { return $.CFEqual(parent, element); }))
+      failure('claude_desktop_ui_changed', 'Another window or control covers the selected Claude action. Retry when it is visible.');
+    var point = $.CGPointMake(x, y);
+    $.CGEventPost(0, $.CGEventCreateMouseEvent(null, 1, point, 0));
+    $.CGEventPost(0, $.CGEventCreateMouseEvent(null, 2, point, 0));
+  }
+  var area;
+  for (var attempt = 0; attempt < 40; attempt++) {
+    try { area = targetArea(); break; } catch (error) { if (attempt === 39) throw error; pause(0.2); }
+  }
+  // Do not archive an actively generating turn or accept a provider permission,
+  // discard, or trust dialog. Those belong to the provider, not to SIMY.
+  function ensureIdle() {
+    ensureNoActiveWork(app);
+  }
+  ensureIdle();
+  var controls;
+  if (input.operation === 'archive') {
+    var labels = [input.title + 'のその他のオプション', 'More options for ' + input.title];
+    controls = descendants(area, function(element) {
+      return textAttribute(element, 'AXRole') === 'AXPopUpButton' && labels.indexOf(textAttribute(element, 'AXDescription')) >= 0 && !hasAncestor(element, function(parent) {
+        return ['サイドバー', 'Sidebar'].indexOf(textAttribute(parent, 'AXDescription')) >= 0 || textAttribute(parent, 'AXDOMIdentifier') === 'frame-peek-popover';
+      });
+    });
+    if (controls.length !== 1) failure('claude_desktop_ui_unavailable', 'The exact Claude conversation menu is unavailable or ambiguous.');
+    var popup = controls[0];
+    function archiveItems() {
+      return descendants(targetArea(), function(element) {
+        return textAttribute(element, 'AXRole') === 'AXMenuItem' && ['アーカイブ', 'Archive'].indexOf(textAttribute(element, 'AXTitle')) >= 0 && hasAncestor(element, function(parent) { return labels.indexOf(textAttribute(parent, 'AXTitle')) >= 0; });
+      });
+    }
+    controls = archiveItems();
+    if (controls.length === 0) {
+      ensureActionTarget(popup);
+      $.AXUIElementPerformAction(popup, $('AXPress')); pause(0.6);
+      controls = archiveItems();
+      if (controls.length === 0) { click(popup); pause(0.6); controls = archiveItems(); }
+    }
+  } else {
+    controls = descendants(area, function(element) { return textAttribute(element, 'AXRole') === 'AXButton' && ['アーカイブ解除', 'Unarchive'].indexOf(textAttribute(element, 'AXTitle')) >= 0; });
+  }
+  if (controls.length !== 1) failure('claude_desktop_ui_unavailable', 'The native archive or restore action is unavailable or ambiguous.');
+  ensureIdle();
+  ensureActionTarget(controls[0]);
+  if ($.AXUIElementPerformAction(controls[0], $('AXPress')) !== 0) failure('claude_desktop_native_unconfirmed', 'The native Claude action did not return a confirmed result.');
+  // Only the caller's independent provider readback can report success.
+  return { dispatched: true, version: version };
+}
+function run(argv) {
+  try { return JSON.stringify({ ok: true, data: perform(JSON.parse(argv[0])) }); }
+  catch (error) { return JSON.stringify({ ok: false, mutationPossible: !error.code || error.code === 'claude_desktop_native_unconfirmed', code: error.code || 'claude_desktop_ui_unavailable', message: error.code ? error.message : 'Claude Desktop native control is unavailable. Open its Code tab and retry.' }); }
+}

package/src/session-supervision/claude-desktop-target.js

@@ -0,0 +1,87 @@
+import { constants } from 'node:fs';
+import { lstat, open, readdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { claudeDesktopSessionRoot } from './claude-desktop-lineage.js';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const LOCAL = /^local_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const fail = message => Object.assign(new Error(message), { code: 'claude_desktop_identity_unverified' });
+const changed = () => Object.assign(fail('Claude Desktop metadata changed.'), { retryable: true });
+const fingerprint = stat => [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(':');
+
+async function directory(path) {
+  const stat = await lstat(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw fail('Claude Desktop storage is not a regular directory.');
+}
+
+// Mutation identity must be resolved from a complete scan, not the bounded,
+// eventually refreshed catalog. Do not expose account settings or transcript text.
+export async function resolveClaudeDesktopTarget(candidate, { home = homedir(), root = claudeDesktopSessionRoot(home) } = {}) {
+  if (candidate?.provider !== 'claude' || !UUID.test(candidate.session || '') || !isAbsolute(candidate.cwd || ''))
+    throw fail('Select an exact Claude conversation.');
+  await directory(root);
+  const matches = []; let inspected = 0;
+  const accounts = await readdir(root, { withFileTypes: true });
+  for (const account of accounts.filter(item => UUID.test(item.name))) {
+    const accountPath = join(root, account.name); await directory(accountPath);
+    for (const org of (await readdir(accountPath, { withFileTypes: true })).filter(item => UUID.test(item.name))) {
+      const partition = join(accountPath, org.name); await directory(partition);
+      const entries = (await readdir(partition, { withFileTypes: true })).filter(entry => entry.name.endsWith('.json') && LOCAL.test(entry.name.slice(0, -5)));
+      inspected += entries.length;
+      if (inspected > 16384) throw fail('Claude Desktop identity scan exceeded its limit.');
+      const readEntry = async entry => {
+        const path = join(partition, entry.name), before = await lstat(path, { bigint: true });
+        if (!before.isFile() || before.isSymbolicLink() || before.size > 262144n) throw fail('Claude Desktop metadata cannot be verified.');
+        const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+        let item;
+        try {
+          if (fingerprint(await handle.stat({ bigint: true })) !== fingerprint(before)) throw changed();
+          // Bound allocation even if the provider replaces/grows metadata while
+          // it is being read. Read one extra byte to detect oversized content.
+          const bytes = Buffer.alloc(262145);
+          let length = 0;
+          while (length < bytes.length) {
+            const { bytesRead } = await handle.read(bytes, length, bytes.length - length, length);
+            if (!bytesRead) break;
+            length += bytesRead;
+          }
+          if (length > 262144) throw fail('Claude Desktop metadata exceeds its size limit.');
+          if (fingerprint(await handle.stat({ bigint: true })) !== fingerprint(before) || fingerprint(await lstat(path, { bigint: true })) !== fingerprint(before)) throw changed();
+          try { item = JSON.parse(bytes.subarray(0, length).toString('utf8')); }
+          catch { throw fail('Claude Desktop metadata is invalid JSON.'); }
+          if (!item || typeof item !== 'object' || Array.isArray(item)) throw fail('Claude Desktop metadata is invalid.');
+          if (fingerprint(await handle.stat({ bigint: true })) !== fingerprint(before) || fingerprint(await lstat(path, { bigint: true })) !== fingerprint(before))
+            throw changed();
+        } finally { await handle.close(); }
+        if (item.cliSessionId !== candidate.session) return;
+        // Include competing claims even when their cwd differs. A CLI UUID alone
+        // must never select a Desktop account or organization implicitly.
+        matches.push({ desktopId: item.sessionId, session: item.cliSessionId, cwd: item.cwd,
+          title: item.title, archived: item.isArchived,
+          partition: createHash('sha256').update(account.name + '/' + org.name).digest('hex'),
+          fileId: entry.name.slice(0, -5) });
+      };
+      // Bound concurrent descriptors while avoiding a serial full scan for each
+      // readback. Wait for every opened descriptor to close before failing.
+      for (let offset = 0; offset < entries.length; offset += 8) {
+        const results = await Promise.allSettled(entries.slice(offset, offset + 8).map(async entry => {
+          for (let attempt = 0; ; attempt++) {
+            try { return await readEntry(entry); }
+            catch (error) { if (!error.retryable || attempt >= 2) throw error; }
+          }
+        }));
+        const failed = results.find(result => result.status === 'rejected');
+        if (failed) throw failed.reason;
+      }
+    }
+  }
+  if (matches.length !== 1) throw fail('Claude conversation is missing or belongs to multiple Desktop records.');
+  const target = matches[0];
+  if (target.desktopId !== target.fileId || !LOCAL.test(target.desktopId || '') || !isAbsolute(target.cwd || '') || resolve(target.cwd) !== resolve(candidate.cwd) ||
+      typeof target.archived !== 'boolean' || typeof target.title !== 'string' || !target.title.trim() || target.title.length > 512)
+    throw fail('Claude Desktop identity or archive state does not match the selected conversation.');
+  const { fileId, ...verified } = target;
+  return verified;
+}

package/src/session-supervision/claude-outcome-review.js

@@ -0,0 +1,132 @@
+import { createHash } from 'node:crypto';
+import { CLAUDE_REVIEW_SYSTEM, CLAUDE_REVIEW_SCHEMA, CLAUDE_NATIVE_REVIEW_TYPE } from './claude-review-definition.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { basename, relative, resolve } from 'node:path';
+import { runStructuredProviderReview } from '../sqm/review-worker.js';
+import { captureAcceptanceReads } from './acceptance-reads.js';
+import { readClaudeConversation, readClaudeNativeReview } from './claude-sessions.js';
+import { independentRequestContext, workspaceIdentity } from './purpose-verification.js';
+import { effectiveAcceptanceCriteria } from '../codex-plugins/simy/hooks/acceptance-policy.mjs';
+import { liveOutcomeReviewEligible, settleLiveOutcomeReview, readRecord, taskDirectory, hasPendingUserStop, providerLinkState, processIdentity } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+
+// Native --max-budget-usd belongs to the original process. A separate reviewer
+// cannot debit that allowance, and copying it would permit twice the spend.
+// Observe only the presence of a cap; never retain or expose the command line.
+export async function claudeReviewBudgetBoundary(record, { platform = process.platform, inspectProcess = processIdentity,
+  readCommand = async pid => platform === 'linux' ? readFile(`/proc/${pid}/cmdline`, 'utf8')
+    : (await promisify(execFile)('/bin/ps', ['-ww', '-p', String(pid), '-o', 'args='], { timeout: 500, maxBuffer: 256 * 1024 })).stdout } = {}) {
+  const owner = record.run?.managed?.liveHookOwner || record.hookSessionProcess;
+  if (!owner?.identity || await inspectProcess(owner.pid) !== owner.identity) return 'unknown';
+  try {
+    if (!['linux', 'darwin'].includes(platform)) return 'unknown';
+    const command = await readCommand(owner.pid);
+    if (await inspectProcess(owner.pid) !== owner.identity) return 'unknown';
+    if (platform === 'darwin') {
+      // Do not mistake a rewritten process title for CLI arguments.
+      const executable = owner.identity.match(/^\S+\s+\S+\s+\d+\s+\S+\s+\d+\s+(.+)$/)?.[1];
+      if (!executable || !/(?:^|\/)(?:claude|node)(?:$|\/)/.test(executable)) return 'unknown';
+      const prefix = [executable, basename(executable)].find(path => command.trimStart().startsWith(`${path} `));
+      if (!prefix || !/(?:^|\s)--?[a-z]/i.test(command.trimStart().slice(prefix.length))) return 'unknown';
+      // ps cannot distinguish a quoted prompt from a cap option. Both cases
+      // may use the original process's native Agent, never a separate reviewer.
+      if (command.includes('--max-budget-usd')) return 'native_only';
+    } else {
+      const argv = command.split('\0');
+      if (argv.at(-1) === '') argv.pop();
+      // A process title can replace argv; padding NULs are not arguments.
+      if (argv.filter(Boolean).length < 2) return 'unknown';
+      const end = argv.indexOf('--');
+      // A Node runtime separator may precede the CLI script. Do not mistake
+      // that ambiguous launcher form for the end of Claude's own options.
+      if (end >= 0 && basename(argv[0]) === 'node' && argv[1]?.startsWith('-')) return 'unknown';
+      const options = end < 0 ? argv : argv.slice(0, end);
+      if (options.some(arg => arg === '--max-budget-usd' || arg.startsWith('--max-budget-usd='))) return 'worker_cap';
+    }
+    return 'no_native_cap_observed';
+  } catch { return 'unknown'; }
+}
+
+// A checkpoint is already committed before this bounded, tool-free review. The
+// original Claude process waits for its CLI child and retains its writer lease.
+// No second controller/session resumes or writes the task workspace.
+export async function reviewClaudeCheckpoint(record, { root, review = runStructuredProviderReview,
+  readContext = readClaudeConversation, readNativeReview = readClaudeNativeReview, onFailure = () => {}, captureReads = captureAcceptanceReads, inspectBudget = claudeReviewBudgetBoundary, signal, executionTimeoutMs = 120000 } = {}) {
+  if (!liveOutcomeReviewEligible(record)) return record;
+  const snapshot = structuredClone(record), cwd = taskDirectory(record), criteria = effectiveAcceptanceCriteria(record.run.managed);
+  const abort = new AbortController();
+  const combined = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
+  const current = async () => {
+    const live = await readRecord(root, record.provider, record.session);
+    const owner = live?.run?.managed?.liveHookOwner;
+    return (!owner || await processIdentity(owner.pid) === owner.identity) && liveOutcomeReviewEligible(live) && live.run.id === snapshot.run.id && live.run.revision === snapshot.run.revision && live.run.controlRevision === snapshot.run.controlRevision &&
+      !hasPendingUserStop(root, live) && (await providerLinkState(root, record.provider)).connected;
+  };
+  const unavailable = async summary => settleLiveOutcomeReview({ root, provider: record.provider, session: record.session, snapshot,
+    review: { passed: false, inspectionAvailable: false, summary, findings: [], source: 'controller_review_unavailable', checkedAt: Date.now() } });
+  let checking = false;
+  const timer = setInterval(async () => {
+    if (checking) return; checking = true;
+    try { if (!await current()) abort.abort(); } catch { abort.abort(); } finally { checking = false; }
+  }, 500);
+  try {
+    const budget = await inspectBudget(record);
+    if (budget === 'unknown') return await settleLiveOutcomeReview({ root, provider: record.provider, session: record.session, snapshot,
+      review: { passed: false, inspectionAvailable: false, budgetBoundary: 'unknown',
+        summary: 'Independent review was not dispatched: the original Claude process budget arguments could not be verified. Acceptance remains unverified; inspect the original launch configuration without changing its budget.',
+        findings: [], source: 'controller_review_unavailable', checkedAt: Date.now() } });
+    const inventory = [];
+    const before = await workspaceIdentity(cwd, undefined, inventory, { signal: combined, inventoryLimit: 1000 });
+    const reads = await captureReads(cwd, criteria, { signal: combined });
+    // This executor cannot independently inspect unnamed artifacts or services.
+    // Never turn absent/truncated input into a successful semantic judgment.
+    if (!reads.length || reads.some(row => row.observation.truncated || row.observation.redacted)) return await unavailable('Current outcome observations are absent or incomplete.');
+    if (reads.some(row => !inventory.some(file => file.type === 'file' && file.path === relative(cwd, resolve(cwd, row.recipe.path)) && file.digest === row.digest)))
+      return await unavailable('Controller observations do not match the reviewed workspace revision; reread the actual outcome.');
+    const context = await readContext(record, { signal: combined, userOnly: true });
+    if (!context?.messages?.some(row => row.role === 'user') || context.incomplete || context.truncated) return await unavailable('Original user context could not be read completely; inspect the original request before retrying review.');
+    if (!await current()) return await readRecord(root, record.provider, record.session);
+    const requests = independentRequestContext(context);
+    if (budget === 'worker_cap' || budget === 'native_only') {
+      const contextDigest = createHash('sha256').update(JSON.stringify(requests.messages.filter(row => row.text?.trim()))).digest('hex');
+      const pending = record.run.managed.nativeOutcomeReview;
+      if (pending && pending.runId === record.run.id && pending.controlRevision === record.run.controlRevision && pending.criteriaDigest === createHash('sha256').update(JSON.stringify(criteria)).digest('hex') && JSON.stringify(pending.owner) === JSON.stringify(record.run.managed.liveHookOwner || record.hookSessionProcess) && pending.workspaceDigest === before && pending.contextDigest === contextDigest) {
+        const native = await readNativeReview(record, pending, { signal: combined });
+        if (!native) return await settleLiveOutcomeReview({ root, provider: record.provider, session: record.session, snapshot,
+          review: { passed: false, inspectionAvailable: false, budgetBoundary: budget, source: 'controller_review_unavailable', checkedAt: Date.now(), findings: [],
+            summary: 'The native independent review has no complete, exact original-session receipt. Keep the original Claude budget and acceptance pending; do not launch a separate reviewer or repeat the native review automatically.' } });
+        if (!await current()) return await readRecord(root, record.provider, record.session);
+        return await settleLiveOutcomeReview({ root, provider: record.provider, session: record.session, snapshot,
+          review: { ...native.output, passed: native.output.passed && native.output.inspectionAvailable, workspaceDigest: before,
+            source: 'independent_claude_review', executionSource: 'native_budgeted_subagent', nativeAgentId: native.agentId,
+            nativeToolUseId: native.toolUseId, contextPolicy: 'user_requests_and_controller_file_reads', checkedAt: Date.now() } });
+      }
+      const prompt = JSON.stringify({ objective: record.run.objective, requests, criteria,
+        workspaceInventory: { paths: inventory.map(row => row.path), truncated: inventory.truncated === true }, observations: reads });
+      return await settleLiveOutcomeReview({ root, provider: record.provider, session: record.session, snapshot,
+        review: { passed: false, inspectionAvailable: false, nativeRequest: { prompt, runId: record.run.id, controlRevision: record.run.controlRevision, criteriaDigest: createHash('sha256').update(JSON.stringify(criteria)).digest('hex'), agentType: CLAUDE_NATIVE_REVIEW_TYPE,
+          workspaceDigest: before, contextDigest, owner: record.run.managed.liveHookOwner || record.hookSessionProcess, requestedAt: Date.now() },
+          summary: 'Independent review will run in a fresh native subagent under the original Claude process budget.', findings: [] } });
+    }
+    const result = await review('claude', {
+      system: CLAUDE_REVIEW_SYSTEM,
+      prompt: JSON.stringify({ objective: record.run.objective, requests: independentRequestContext(context), criteria, workspaceInventory: { paths: inventory.map(row => row.path), truncated: inventory.truncated === true }, observations: reads }),
+      output_schema: CLAUDE_REVIEW_SCHEMA
+    }, { signal: combined, executionTimeoutMs, subscriptionOnly: true, beforeDispatch: async () => {
+      if (!await current()) throw new Error('Review target changed');
+    } });
+    const value = result.output;
+    if (typeof value?.passed !== 'boolean' || typeof value.inspectionAvailable !== 'boolean' || typeof value.summary !== 'string' || !Array.isArray(value.findings) ||
+        value.findings.some(row => typeof row !== 'string')) return await unavailable('Independent provider returned an unusable assessment; inspect provider availability before retrying.');
+    if (!await current()) return await readRecord(root, record.provider, record.session);
+    return await settleLiveOutcomeReview({ root, provider: record.provider, session: record.session, snapshot,
+      review: { passed: value.passed && value.inspectionAvailable, inspectionAvailable: value.inspectionAvailable, summary: value.summary.slice(0, 4000), findings: value.findings.slice(0, 20),
+        workspaceDigest: before, source: 'independent_claude_review', contextPolicy: 'user_requests_and_controller_file_reads', checkedAt: Date.now() } });
+  } catch (error) {
+    onFailure(error);
+    // Failure to inspect is not a product defect or successful acceptance.
+    if (!await current()) return await readRecord(root, record.provider, record.session);
+    return await unavailable('Independent provider inspection failed; inspect the existing provider connection and retry the original outcome check.');
+  } finally { clearInterval(timer); }
+}