openplanr 3.3.0 → 3.5.0

package/lib/host-packages/cursor/openplanr/rules/planr-delegate/scripts/integration-files.mjs

@@ -1,18 +1,8 @@
 import { execFile as execFileCallback } from 'node:child_process';
-import { createHash, randomUUID } from 'node:crypto';
-import {
-  linkSync,
-  lstatSync,
-  readFileSync,
-  readlinkSync,
-  renameSync,
-  symlinkSync,
-  unlinkSync,
-} from 'node:fs';
-import { chmod, lstat, mkdir, readFile, rename, rm, symlink, writeFile } from 'node:fs/promises';
-import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { lstat } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
-import { captureFileState, gitFileState, headFileState } from './custody.mjs';
+import { captureFileState, headFileState } from './custody.mjs';
 
 const execFile = promisify(execFileCallback);
 const gitOptions = { encoding: 'buffer', maxBuffer: 32 * 1024 * 1024 };
@@ -81,303 +71,6 @@ export async function safeDestination(root, path) {
   return full;
 }
 
-export async function putState(root, path, state, suffix, createdDirectories = []) {
-  const target = await safeDestination(root, path);
-  if (state.kind === 'absent') {
-    await rm(target, { force: true });
-    return;
-  }
-  const missing = [];
-  let directory = dirname(target);
-  while (directory !== resolve(root)) {
-    try {
-      await lstat(directory);
-      break;
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-      missing.push(directory);
-      directory = dirname(directory);
-    }
-  }
-  for (const created of missing.reverse()) {
-    await mkdir(created);
-    createdDirectories.push(created);
-  }
-  const temporary = `${target}.planr-delegate-${suffix}`;
-  try {
-    if (state.kind === 'file') {
-      await writeFile(temporary, Buffer.from(state.contentBase64, 'base64'), {
-        mode: 0o600,
-        flag: 'wx',
-      });
-      await chmod(temporary, state.mode);
-    } else if (state.kind === 'symlink') {
-      if (
-        isAbsolute(state.target) ||
-        !resolve(dirname(target), state.target).startsWith(`${resolve(root)}${sep}`)
-      )
-        throw new IntegrationError('E_INTEGRATION_LINK', 'Delegate symlink target is unsafe.', {
-          path,
-        });
-      await symlink(state.target, temporary);
-    } else throw new IntegrationError('E_INTEGRATION_STATE', 'Unsupported file state.', { path });
-    await rename(temporary, target);
-  } finally {
-    await rm(temporary, { force: true });
-  }
-}
-
-export function retainedEntryState(file) {
-  try {
-    const info = lstatSync(file);
-    if (info.isSymbolicLink())
-      return { kind: 'symlink', mode: info.mode & 0o777, target: readlinkSync(file) };
-    if (!info.isFile())
-      throw new IntegrationError('E_INTEGRATION_STATE', 'Destination is not a file.', {
-        path: file,
-      });
-    return {
-      kind: 'file',
-      mode: info.mode & 0o777,
-      contentBase64: readFileSync(file).toString('base64'),
-    };
-  } catch (error) {
-    if (error.code === 'ENOENT') return { kind: 'absent' };
-    throw error;
-  }
-}
-
-const LOCAL_CUSTODY = '.planr-delegate-write-custody';
-
-async function privateDirectory(path, create = true) {
-  if (create)
-    await mkdir(path, { mode: 0o700 }).catch((error) => {
-      if (error.code !== 'EEXIST') throw error;
-    });
-  const info = await lstat(path);
-  if (
-    !info.isDirectory() ||
-    info.isSymbolicLink() ||
-    (info.mode & 0o077) !== 0 ||
-    (process.getuid && info.uid !== process.getuid())
-  )
-    throw new IntegrationError(
-      'E_INTEGRATION_CUSTODY',
-      'Write custody is not a private directory.',
-    );
-}
-
-// Git metadata can be on another volume. Keep claims and staging beside the
-// destination in that case, and save the location before the first source write.
-async function writeCustody(root, target, suffix, create = true) {
-  if (basename(safePath(suffix)) !== suffix)
-    throw new IntegrationError('E_INTEGRATION_CUSTODY', 'Invalid write custody identifier.');
-  const gitDirectory = (await git(root, 'rev-parse', '--absolute-git-dir')).toString('utf8').trim();
-  const base = resolve(gitDirectory, 'planr-delegate-write-custody');
-  const metadata = resolve(base, suffix);
-  for (const directory of [base, metadata]) {
-    try {
-      await privateDirectory(directory, false);
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-    }
-  }
-  const reference = resolve(metadata, 'location.json');
-  let location;
-  try {
-    location = JSON.parse(await readFile(reference, 'utf8'));
-  } catch (error) {
-    if (error.code !== 'ENOENT') throw error;
-  }
-  if (location) {
-    const directory = await safeDestination(root, location.path);
-    const anchor = dirname(dirname(directory));
-    if (
-      basename(directory) !== suffix ||
-      basename(dirname(directory)) !== LOCAL_CUSTODY ||
-      !target.startsWith(`${anchor}${sep}`)
-    )
-      throw new IntegrationError('E_INTEGRATION_CUSTODY', 'Write custody location changed.');
-    await privateDirectory(dirname(directory), false);
-    await privateDirectory(directory, false);
-    return directory;
-  }
-  if (!create) return metadata;
-  await privateDirectory(base);
-  await privateDirectory(metadata);
-  let anchor = dirname(target);
-  let info;
-  for (;;) {
-    try {
-      info = await lstat(anchor);
-      break;
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-      anchor = dirname(anchor);
-    }
-  }
-  if (info.dev === (await lstat(gitDirectory)).dev) return metadata;
-  const local = resolve(anchor, LOCAL_CUSTODY);
-  await privateDirectory(local);
-  const ignore = resolve(local, '.gitignore');
-  try {
-    await writeFile(ignore, '*\n', { flag: 'wx', mode: 0o600 });
-  } catch (error) {
-    if (error.code !== 'EEXIST' || (await readFile(ignore, 'utf8')) !== '*\n') throw error;
-  }
-  const directory = resolve(local, suffix);
-  await privateDirectory(directory);
-  await writeFile(reference, JSON.stringify({ path: relative(root, directory) }), {
-    flag: 'wx',
-    mode: 0o600,
-  });
-  return directory;
-}
-
-function parentEntries(root, target) {
-  const entries = [];
-  for (let path = dirname(target); ; path = dirname(path)) {
-    const info = lstatSync(path);
-    if (!info.isDirectory() || info.isSymbolicLink())
-      throw new IntegrationError(
-        'E_INTEGRATION_PATH',
-        'Destination parent is not a real directory.',
-      );
-    entries.push({ path, dev: info.dev, ino: info.ino });
-    if (path === resolve(root)) return entries;
-  }
-}
-
-function assertParentEntries(entries) {
-  for (const entry of entries) {
-    const info = lstatSync(entry.path);
-    if (
-      !info.isDirectory() ||
-      info.isSymbolicLink() ||
-      info.dev !== entry.dev ||
-      info.ino !== entry.ino
-    )
-      throw new IntegrationError(
-        'E_INTEGRATION_SOURCE_DRIFT',
-        'Destination parent changed during integration.',
-        { path: entry.path },
-      );
-  }
-}
-
-// Claim the current directory entry, inspect the claimed bytes, then publish with
-// exclusive link creation. A concurrent replacement is never overwritten. Claimed
-// entries remain private for crash recovery and for writers holding the old inode.
-export async function putStateGuarded(
-  root,
-  path,
-  state,
-  expected,
-  suffix,
-  createdDirectories = [],
-) {
-  const target = await safeDestination(root, path);
-  const custody = await writeCustody(root, target, suffix);
-  const key = createHash('sha256').update(path).digest('hex');
-  const claimed = resolve(custody, `${key}.before`);
-  const staged = `${key}.after-${randomUUID()}`;
-  await assertSafeChanges(root, [{ path, after: state }]);
-  if (state.kind === 'file') {
-    await writeFile(resolve(custody, staged), Buffer.from(state.contentBase64, 'base64'), {
-      flag: 'wx',
-      mode: 0o600,
-    });
-    await chmod(resolve(custody, staged), state.mode);
-  } else if (state.kind === 'symlink') await symlink(state.target, resolve(custody, staged));
-  const missing = [];
-  let directory = dirname(target);
-  while (directory !== resolve(root)) {
-    try {
-      await lstat(directory);
-      break;
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-      missing.push(directory);
-      directory = dirname(directory);
-    }
-  }
-  for (const created of missing.reverse()) {
-    await mkdir(created);
-    createdDirectories.push(created);
-  }
-  const parents = parentEntries(root, target);
-  let moved = false;
-  let published = false;
-  try {
-    if (expected.kind !== 'absent') {
-      try {
-        if (retainedEntryState(claimed).kind === 'absent') renameSync(target, claimed);
-        moved = true;
-      } catch (error) {
-        if (error.code !== 'ENOENT') throw error;
-      }
-      if (!moved || !sameState(retainedEntryState(claimed), expected))
-        throw new IntegrationError(
-          'E_INTEGRATION_SOURCE_DRIFT',
-          'Destination changed before its write was claimed.',
-          { path, retainedPath: moved ? claimed : null },
-        );
-    }
-    assertParentEntries(parents);
-    // link is atomic and fails if an editor created a replacement during the claim.
-    if (state.kind !== 'absent') {
-      if (state.kind === 'symlink') symlinkSync(state.target, target);
-      else linkSync(resolve(custody, staged), target);
-      published = true;
-    } else if (retainedEntryState(target).kind !== 'absent')
-      throw new IntegrationError(
-        'E_INTEGRATION_SOURCE_DRIFT',
-        'A concurrent replacement blocks deletion.',
-        { path, retainedPath: claimed },
-      );
-    assertParentEntries(parents);
-    if (moved && !sameState(retainedEntryState(claimed), expected))
-      throw new IntegrationError(
-        'E_INTEGRATION_SOURCE_DRIFT',
-        'A writer changed the claimed original; retained for recovery.',
-        { path, retainedPath: claimed },
-      );
-    return moved ? claimed : null;
-  } catch (error) {
-    if (published)
-      error.details = { ...error.details, published: true, path, retainedPath: claimed };
-    if (moved) {
-      // Restore exclusively: an owner's replacement always takes precedence.
-      try {
-        assertParentEntries(parents);
-        const original = retainedEntryState(claimed);
-        if (original.kind === 'symlink') symlinkSync(original.target, target);
-        else linkSync(claimed, target);
-      } catch (restoreError) {
-        if (restoreError.code !== 'EEXIST')
-          error.details = { ...error.details, restoreCode: restoreError.code };
-      }
-    }
-    if (error.code === 'EEXIST')
-      throw new IntegrationError(
-        'E_INTEGRATION_SOURCE_DRIFT',
-        'A concurrent destination was preserved.',
-        { path, retainedPath: moved ? claimed : null },
-      );
-    throw error;
-  } finally {
-    if (state.kind !== 'absent') {
-      try {
-        unlinkSync(resolve(custody, staged));
-      } catch (error) {
-        // Staging is private and recoverable; cleanup failure must not replace a write conflict.
-        if (error.code !== 'ENOENT')
-          process.emitWarning(`Private write staging cleanup failed: ${error.code}`);
-      }
-    }
-  }
-}
-
 export async function workingPaths(root) {
   const [tracked, untracked] = await Promise.all([
     git(root, 'diff', '--name-only', '-z', 'HEAD'),
@@ -426,75 +119,3 @@ export async function assertSafeChanges(root, changes) {
       });
   }
 }
-
-export async function rollbackWritten(root, changes, suffix) {
-  const errors = [];
-  for (const change of [...changes].reverse()) {
-    try {
-      const current = await captureFileState(root, change.path);
-      if (sameState(current, change.sourceBefore)) continue;
-      let claimed;
-      if (change.writeId) {
-        const target = await safeDestination(root, change.path);
-        const directory = await writeCustody(root, target, change.writeId, false);
-        const file = `${createHash('sha256').update(change.path).digest('hex')}.before`;
-        claimed = retainedEntryState(resolve(directory, file));
-        if (claimed.kind !== 'absent' && !sameState(claimed, change.sourceBefore)) {
-          errors.push({
-            path: change.path,
-            retainedPath: resolve(directory, file),
-            code: 'E_INTEGRATION_ROLLBACK_CONFLICT',
-          });
-          continue;
-        }
-      }
-      if (
-        current.kind === 'absent' &&
-        claimed?.kind !== 'absent' &&
-        claimed &&
-        sameState(claimed, change.sourceBefore)
-      ) {
-        await putStateGuarded(
-          root,
-          change.path,
-          change.sourceBefore,
-          current,
-          `${suffix}-interrupted`,
-        );
-        continue;
-      }
-      if (!sameState(current, change.after)) {
-        errors.push({ path: change.path, code: 'E_INTEGRATION_ROLLBACK_CONFLICT' });
-        continue;
-      }
-      await putStateGuarded(
-        root,
-        change.path,
-        change.sourceBefore,
-        change.after,
-        change.writeId ? `${change.writeId}-rollback` : `${suffix}-rollback`,
-      );
-    } catch (error) {
-      errors.push({ path: change.path, code: error.code ?? 'E_INTEGRATION_ROLLBACK' });
-    }
-  }
-  return errors;
-}
-
-export async function treeIdentity(root, overrides = new Map()) {
-  const paths = new Set(
-    (await git(root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'))
-      .toString('utf8')
-      .split('\0')
-      .filter(Boolean),
-  );
-  for (const path of overrides.keys()) paths.add(path);
-  const hash = createHash('sha256');
-  for (const path of [...paths].sort()) {
-    const state = overrides.get(path) ?? (await captureFileState(root, safePath(path)));
-    const logical = await gitFileState(root, path, state);
-    if (logical.kind !== 'absent')
-      hash.update(path).update('\0').update(JSON.stringify(logical)).update('\0');
-  }
-  return hash.digest('hex');
-}

package/lib/host-packages/cursor/openplanr/rules/planr-delegate/scripts/presentation.mjs

@@ -94,6 +94,16 @@ export function handoffPresentation(outcome) {
   };
 }
 
+function warningText({ refs, omitted }) {
+  return `Refs changed outside this run (not blocking): ${refs.join(', ')}${omitted ? ` and ${omitted} more` : ''}`;
+}
+
+function violationText({ code, path, ref, change, omitted }) {
+  if (omitted) return `${code}: ${omitted} more path(s)`;
+  if (!path) return ref ? `${code}: ${ref}` : code;
+  return change ? `${code}: ${path} (${change})` : `${code}: ${path}`;
+}
+
 export function reviewPresentation(review) {
   return {
     phase: 'review',
@@ -102,7 +112,8 @@ export function reviewPresentation(review) {
       ? `${review.changedPaths.length} observed file change(s) ready for human review; nothing has been integrated.`
       : 'Observed changes require attention before integration.',
     changed: visiblePaths(review.changedPaths),
-    violations: review.violations.map(({ code, path }) => (path ? `${code}: ${path}` : code)),
+    violations: review.violations.map(violationText),
+    warnings: (review.warnings ?? []).map(warningText),
     nextAction: review.ready
       ? 'Inspect the retained worktree patch and then call apply with the same scope.'
       : 'Resolve the violations in the retained worktree or source before retrying.',
@@ -121,7 +132,8 @@ export function implementationReport(result, selector) {
     ...(result.cleanup?.status === 'failed'
       ? ['Owned worktree cleanup failed; integration remains accepted']
       : []),
-    ...(result.violations ?? []).map(({ code, path }) => (path ? `${code}: ${path}` : code)),
+    ...(result.violations ?? []).map(violationText),
+    ...(result.warnings ?? []).map(warningText),
     ...(result.code ? [result.code] : []),
     ...failed.map(({ command, status, exitCode, timeoutMs, classification }) =>
       status === 'timed-out'
@@ -136,6 +148,10 @@ export function implementationReport(result, selector) {
         ]
       : []),
   ];
+  const unselected = result.unselectedDirtyPaths ?? [];
+  const unselectedNote = unselected.length
+    ? ` Checks did not include ${result.unselectedDirtyCount ?? unselected.length} unselected local change(s): ${visiblePaths(unselected)}.`
+    : '';
   return {
     Outcome: accepted
       ? paths.length
@@ -146,16 +162,17 @@ export function implementationReport(result, selector) {
     Changed: paths.length
       ? `${paths.length} observed file(s) ${accepted ? 'integrated' : 'not accepted'}: ${visiblePaths(paths)}`
       : 'No observed file changes.',
-    Checks: checks.length
-      ? `${checks.filter(({ status }) => status === 'passed').length}/${checks.length} independent check(s) passed: ${checks
-          .map(
-            ({ command, status, durationMs }) =>
-              `${command} (${status}${
-                durationMs === undefined ? '' : `, ${(durationMs / 1000).toFixed(1)}s`
-              })`,
-          )
-          .join(', ')}`
-      : 'No independent checks ran; verification remains unconfirmed.',
+    Checks:
+      (checks.length
+        ? `${checks.filter(({ status }) => status === 'passed').length}/${checks.length} independent check(s) passed: ${checks
+            .map(
+              ({ command, status, durationMs }) =>
+                `${command} (${status}${
+                  durationMs === undefined ? '' : `, ${(durationMs / 1000).toFixed(1)}s`
+                })`,
+            )
+            .join(', ')}${unselectedNote ? '.' : ''}`
+        : 'No independent checks ran; verification remains unconfirmed.') + unselectedNote,
     Issues: issues.length
       ? `${issues.join('; ')}.${accepted ? '' : ` ${result.nextAction ?? ''}`}`.trim()
       : 'None found in this review.',

package/lib/host-packages/cursor/openplanr/rules/planr-delegate/scripts/run-contract.mjs

@@ -55,6 +55,17 @@ export function integrationPaths(paths) {
             'E_DELEGATE_SCOPE',
             'Integration paths must be safe repository-relative paths.',
           );
+        // Scope entries are literal prefixes; a glob would only fail later at review.
+        const parts = path.split('/');
+        const glob = parts.findIndex((part) => /[*?]/u.test(part));
+        if (glob !== -1) {
+          throw new DelegateRunError(
+            'E_DELEGATE_SCOPE',
+            glob > 0
+              ? `Integration paths are literal path prefixes, not globs; use "${parts.slice(0, glob).join('/')}" instead of "${path}".`
+              : `Integration paths are literal path prefixes, not globs; list the files or directories "${path}" should cover.`,
+          );
+        }
         return path;
       }),
     ),

package/lib/host-packages/cursor/openplanr/rules/planr-delegate/scripts/run-execution.mjs

@@ -42,7 +42,7 @@ const SAFE_ADAPTER_DIAGNOSTICS = Object.freeze({
   E_ADAPTER_PROCESS_IDENTITY:
     'Process identity inspection is unavailable. Restore normal host process inspection before retrying; native permissions were not changed.',
   E_ADAPTER_PERMISSION:
-    'Native permission needs attention. Resolve it in the native configuration, then continue this exact session; permissions are never weakened automatically.',
+    'Native permission needs attention. Resolve it in the native configuration, then continue this exact session; permissions are never bypassed automatically.',
   E_ADAPTER_RESULT:
     'Native execution ended without terminal evidence; inspect the exact session and retained worktree.',
   E_ADAPTER_MODEL_TEMPLATE:

package/lib/host-packages/cursor/openplanr/rules/planr-delegate/scripts/run-lifecycle.mjs

@@ -5,7 +5,7 @@ import { basename, dirname, join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { terminateProcessGroup } from './adapters/generic.mjs';
 import { captureFileState, cleanupWorktreeCustody, validateWorktreeCustody } from './custody.mjs';
-import { git, treeIdentity } from './integration-files.mjs';
+import { git } from './integration-files.mjs';
 import {
   implementationReport,
   liveExecutionTiming,
@@ -118,8 +118,13 @@ async function initialAbandonmentInventory(record, custody) {
     (record.initialIndex && record.initialIndex !== custody.initialIndex)
   )
     throw abandonError(record, 'The initial worktree HEAD, index or protected contents changed.');
+  if (
+    custody.base &&
+    (await git(target, 'rev-parse', 'HEAD')).toString('utf8').trim() !== custody.base
+  )
+    throw abandonError(record, 'The run branch advanced past its base commit.');
   const entries = new Map(
-    (await git(target, 'ls-tree', '-r', '-z', custody.initialHead))
+    (await git(target, 'ls-tree', '-r', '-z', custody.base ?? custody.initialHead))
       .toString('utf8')
       .split('\0')
       .filter(Boolean)
@@ -338,6 +343,12 @@ export async function recoverDelegateRun({ runId, runDirectory = defaultRunDirec
   });
 }
 
+async function worktreeAtTip(target, tip) {
+  const head = (await git(target, 'rev-parse', 'HEAD')).toString('utf8').trim();
+  const status = await git(target, 'status', '--porcelain=v1', '-z', '--untracked-files=all');
+  return head === tip && status.length === 0;
+}
+
 export async function cleanupAcceptedWorktree(record, runDirectory) {
   if (record.cleanup?.status === 'removed') return record.cleanup;
   const disposition = record.disposition === 'integrated' ? 'accepted' : 'abandoned';
@@ -357,11 +368,7 @@ export async function cleanupAcceptedWorktree(record, runDirectory) {
     beforeRemove: async (target) => {
       if (unstarted)
         await assertUnchangedAbandonment(record, await custodyAt(record, runDirectory));
-      if (
-        record.nativeSelection &&
-        record.integration?.worktreeIdentity &&
-        (await treeIdentity(target)) !== record.integration.worktreeIdentity
-      )
+      if (record.integration?.tip && !(await worktreeAtTip(target, record.integration.tip)))
         throw new DelegateRunError(
           'E_DELEGATE_CLEANUP_DRIFT',
           'Owned worktree changed after acceptance; retain it for inspection.',
@@ -450,9 +457,6 @@ export async function delegateRunStatus({ runId, runDirectory = defaultRunDirect
       ? {
           status: record.integration.status,
           phase: record.integration.phase,
-          journalPath: record.integration.journalPath,
-          cursor: record.integration.cursor,
-          pendingPath: record.integration.pendingPath,
           nextAction: `Run node ${record.helper?.integrationPath ?? 'integrate.mjs'} recover with this run ID and resolution rollback (default) or accept after verifying every written path.`,
         }
       : null,

package/lib/host-packages/cursor/openplanr/rules/planr-delegate/scripts/run-preparation.mjs

@@ -273,6 +273,8 @@ export async function prepareDelegateRun({
       worktreeParent: custodyParent,
       runId,
       native: prepared.profile.kind !== 'generic',
+      branch: true,
+      runDirectory: privateDirectory,
     });
     const custodyPath = join(runPath, 'custody.json');
     await updateRunRecord(
@@ -282,6 +284,8 @@ export async function prepareDelegateRun({
         worktreePath: custody.worktreePath,
         initialHead: custody.initialHead,
         initialIndex: custody.initialIndex,
+        branch: custody.branch,
+        base: custody.base,
       },
       { directory: privateDirectory },
     );

package/lib/host-packages/cursor/openplanr/rules/planr-delegate/scripts/run-record.mjs

@@ -17,7 +17,7 @@ import { promisify } from 'node:util';
 import { CREDENTIAL_FORMAT } from './credentials.mjs';
 import { captureFileState } from './custody.mjs';
 
-export const RUN_RECORD_SCHEMA_VERSION = '2.0.0';
+export const RUN_RECORD_SCHEMA_VERSION = '3.0.0';
 export const MAX_RUN_RECORD_BYTES = 64 * 1024;
 export const CLOSED_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 
@@ -64,7 +64,7 @@ function encoded(record) {
   if (
     !record ||
     record.kind !== 'openplanr-delegation-run' ||
-    !['1.0.0', RUN_RECORD_SCHEMA_VERSION].includes(record.schemaVersion) ||
+    !['1.0.0', '2.0.0', RUN_RECORD_SCHEMA_VERSION].includes(record.schemaVersion) ||
     !RUN_ID.test(record.runId ?? '')
   ) {
     throw new RunRecordError('E_RUN_FORMAT', 'Invalid delegated run record.');

package/lib/host-packages/cursor/openplanr/rules/planr-delegate.mdc

@@ -67,7 +67,8 @@ digest-acceptance step or permanently frozen setup baseline. See
 
 Use the returned pinned helper for subsequent actions. `dispatch`, bounded `wait`
 and `status` expose the exact session, native progress, inactivity and phase timings.
-Native tools, permissions, configuration and implementation loops remain native.
+Native tools, permissions, configuration and implementation loops remain native, except
+that Claude Code or Codex with no configured permission mode starts in its edit mode.
 Do not add bypass/force/yolo flags, blanket tool exclusions or silent model fallbacks.
 Local backend probes are compatibility diagnostics, not a separate execution policy.
 They read model metadata without submitting inference, loading models or sending

package/lib/host-packages/cursor/openplanr/rules/planr-design/references/design-system.md

@@ -54,11 +54,11 @@ while authoring:
 - at most two families and three weights each; one variable file can cover a
   family's weights.
 
-Snapshot with the bundled helper, run from the skill directory (see
+Snapshot with the design CLI, run from the project directory (see
 [utilities.md](utilities.md)):
 
 ```sh
-node scripts/design.mjs fonts fetch --family "Inter:400,600" --family "Source Serif 4:400" --dest <design>/source/assets/fonts
+openplanr design fonts fetch --family "Inter:400,600" --family "Source Serif 4:400" --dest <design>/source/assets/fonts
 ```
 
 It is the one command to ask approval for. A host that allowlists network access by

package/lib/host-packages/cursor/openplanr/rules/planr-design/references/generation.md

@@ -34,12 +34,12 @@ incidental array positions or rendered CSS selectors.
 
 Author real screen content with useful labels, plausible data and complete states.
 Make the primary journey navigable and meaningful controls functional. Use local
-HTML/CSS/JavaScript and assets supported by the bundled utility; do not require a
+HTML/CSS/JavaScript and assets supported by the design utilities; do not require a
 build server, package installation, remote modules or a development environment to
 open the studio. Third-party assets retain their license/attribution where needed.
 Use classic browser scripts with local event handlers. If adapting an existing
-module-based component, compile its local preview before packaging; the portable
-utility does not install dependencies or compile modules. Use local image `src`
+module-based component, compile its local preview before packaging; the design
+utilities do not install dependencies or compile modules. Use local image `src`
 with responsive CSS. Forms validate and run local handlers; omit navigation
 actions and targets. Cross-screen actions can use `data-design-navigate` with the
 stable target screen ID.

package/lib/host-packages/cursor/openplanr/rules/planr-design/references/hosted-canvas.md

@@ -14,6 +14,8 @@ there. Hosts without one use the local studio unchanged.
 - Use the local studio when the user asks for it, asks for an encrypted company
   review or share link, or the canvas cannot be created or published. Name the
   reason when it is a failure, keep any work already written and continue locally.
+  The local studio needs a ready runtime; without one, end at the matching stop in
+  [utilities.md](utilities.md).
 - Before creating the canvas, say in one line that the design is published to
   the host's service and stays private to the user until they share it.
 
@@ -57,6 +59,7 @@ Name each screen's board file in the screen inventory. This path writes no
 specification and board sources are Plan's inputs.
 
 Return the direction, the canvas link, the specification and board-source paths,
-and the verification status. Review happens in the canvas's own comments; apply
-revisions with the Design type's revising steps and keep the specification in
-step. OpenPlanr Studio cannot open a hosted canvas yet, so do not offer it.
+and the verification status. Review happens in the canvas's own comments: read
+them with the host's artifact comments tool, apply revisions with the Design
+type's revising steps, and keep the specification in step. OpenPlanr Studio
+cannot open a hosted canvas yet, so do not offer it.