@1aboveio/skills 1.0.10 → 1.0.12

package/skills/app-dev/app-debug/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: app-debug
 description: "Diagnose runtime failures in deployed Cloud Run services — 5xx/422 errors, tracebacks, Next.js SSR/hydration or Server Action failures, DB/Secret Manager connection errors, cold-start timeouts, container OOM. NOT for build or deploy failures (cloud-debug)."
-release-version: 0.44.1
+release-version: 0.45.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # App Debug

package/skills/app-dev/better-auth/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: better-auth
 description: "Add or debug Better Auth for Next.js App Router: login, sessions, protected routes, middleware, OAuth (including Feishu/Lark), cookies, Prisma, and Auth.js migration."
-release-version: 0.44.1
+release-version: 0.45.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Better Auth for Next.js

package/skills/app-dev/data-catalog/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: data-catalog
 description: "Column definitions for warehouse tables, written inside the Spark/PySpark or SQL script that builds each table (CATALOG_TABLE / CATALOG_FIELDS, or a `-- @field` comment block), with a generated markdown catalog in docs/catalog/ and a CI check that fails a PR whose catalog is stale. Use when writing or changing a table script that adds, renames, removes, or changes the meaning of an output column or feature; when asked what a warehouse column or feature means; to set a repo up ('init the data catalog', 'generate the data dictionary', '字段字典', 'add catalog CI'); or to audit existing SQL or Spark scripts for undocumented columns. NOT for implementing or tuning the Spark job itself (pyspark), DAG wiring (airflow), or general workflow YAML (github-actions)."
-release-version: 0.44.1
+release-version: 0.45.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Data catalog

package/skills/app-dev/data-quality/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: data-quality
 description: "Check a published warehouse table's data against its data-catalog definitions with read-only SELECTs: columns never filled or stuck at one value, counts below zero, ratios outside 0–1, declared values that never appear and undeclared values that do. Then classify each finding as a wrong definition, wrong code, or wrong data. Use when asked whether a table's data is right, to profile or sanity-check a dwd/ads table, to find dead or constant columns, to check a column's values against its documented list, after a pipeline change ships, or when a data-catalog definition and the data might disagree. NOT for validating a Spark change before it ships (pyspark canary and reconciliation), writing definitions (data-catalog), or monitoring dashboards."
-release-version: 0.44.1
+release-version: 0.45.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Data quality

package/skills/app-dev/ios-foundation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ios-foundation
-description: "Set up and prove an Expo / React Native native iOS workspace from a clean checkout to a manual Login smoke on an owned iOS Simulator: isolated worktree and private caches, Xcode/runtime/CocoaPods preflight, frozen install with `pod install --deployment`, platform-scoped prebuild, an ad-hoc-signed Debug simulator build, a private simulator by exact UDID, Metro on a free port, a disposable PostgreSQL backend with owned cleanup, and the evidence record (setup proof only; feature work reports the smoke result). Use for 'set up iOS', 'build the iOS app', 'run the app on the iOS simulator', 'add iOS to the React Native app', 'prove the iOS build', or when a pod install, xcodebuild, simulator boot, Metro connection or Keychain session fails. NOT for Android (android-foundation), signing, TestFlight or App Store release, or general workflow YAML (github-actions)."
-release-version: 0.44.1
+description: "Set up and prove an Expo / React Native native iOS workspace from an assigned or fresh isolated workspace to a manual Login smoke on an owned iOS Simulator: isolated workspace and private caches, Xcode/runtime/CocoaPods preflight, frozen install with `pod install --deployment`, platform-scoped prebuild, an ad-hoc-signed Debug simulator build, a private simulator by exact UDID, Metro on a free port, a disposable PostgreSQL backend with owned cleanup, and the evidence record (setup proof only; feature work reports the smoke result). Use for 'set up iOS', 'build the iOS app', 'run the app on the iOS simulator', 'add iOS to the React Native app', 'prove the iOS build', or when a pod install, xcodebuild, simulator boot, Metro connection or Keychain session fails. NOT for Android (android-foundation), signing, TestFlight or App Store release, or general workflow YAML (github-actions)."
+release-version: 0.45.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # iOS foundation
@@ -22,16 +22,19 @@ Pick the mode first:
 
 | Step | Read |
 | --- | --- |
-| Shell snippets for every stage below | [references/setup.md](references/setup.md) |
+| Workspace resolution, then shell snippets for every stage | [references/workspace.md](references/workspace.md), [references/setup.md](references/setup.md) |
 | Proving a product change on the simulator | [Feature work](#feature-work) |
 | A stage failed | [Triage](#triage) |
 | Writing up setup proof | [Evidence record](#evidence-record) |
 
 ## Rules
 
-- Work in a dedicated worktree on a new branch from `origin/main`. Never overwrite or reuse
-  another checkout, and never symlink another worktree's `node_modules`, `Pods` or
-  DerivedData.
+- Resolve the workspace first; [references/workspace.md](references/workspace.md) owns
+  precedence: an assigned isolated workspace and candidate HEAD win, feature work, fixes and
+  triage reuse the owned workspace, and standalone setup creates one managed workspace only
+  with no usable assignment. Read its actual HEAD; never substitute `origin/main`, a new
+  branch or another checkout. Never overwrite a peer's checkout, and never symlink another
+  worktree's `node_modules`, `Pods` or DerivedData.
 - Tool shells keep no variables, functions or traps between calls. Write the environment
   to `.cache/ios-env.sh` once and source it at the start of every command. Run the
   disposable database and backend as one long-running command so its cleanup trap holds.
@@ -68,7 +71,8 @@ Pick the mode first:
 
 Run them in this order. Stop at the first failure and triage it.
 
-1. **Checkout and environment.** Add the worktree and export the private cache paths,
+1. **Workspace and environment.** Resolve the assigned or standalone workspace
+   ([references/workspace.md](references/workspace.md)) and export the private cache paths,
    `CP_CACHE_DIR`, `CP_HOME_DIR` and the DerivedData path. Print `xcode-select -p`,
    `xcodebuild -version`, `xcodebuild -showsdks`, `xcrun simctl list runtimes` and
    `devicetypes`, and the node, pnpm, ruby and pod versions. Check that `pod --version`
@@ -110,7 +114,8 @@ Run them in this order. Stop at the first failure and triage it.
 
 - Clean up only what this run started: the simulator by its exact UDID
   (`simctl shutdown`, then `simctl delete`), the container by the ID in its CID file, and
-  the backend and Metro by stopping their own commands.
+  the backend and Metro by stopping their own commands. These are short-lived; the
+  development workspace, its Pods, DerivedData and private caches outlive them.
 - Never use `simctl erase all`, `simctl shutdown all`, `killall Simulator`, broad `pkill`,
   or `docker system prune`.
 - Give every Docker startup, readiness and cleanup command a 30-second limit. Treat exit
@@ -167,8 +172,8 @@ reliable.
 
 For setup proof only. Record:
 
-- Source SHA, host OS and architecture, and the Xcode, iOS SDK, CocoaPods, Ruby, node and
-  pnpm versions.
+- Source SHA and the workspace root/path/base/branch/owner from the lifecycle record; host OS
+  and architecture, and the Xcode, iOS SDK, CocoaPods, Ruby, node and pnpm versions.
 - The simulator runtime, device type and exact UDID (a run identifier, not a shared
   resource), and the bundle identifier.
 - The exit status of pod install, tests, typecheck, export and the native build.

package/skills/app-dev/ios-foundation/references/setup.md

@@ -1,20 +1,31 @@
 # iOS foundation: shell snippets
 
 Replace each `<placeholder>` with the repo's real value. Tool shells do not keep variables,
-functions or traps between calls: step 1 writes `.cache/ios-env.sh`, which also `cd`s into
-the worktree, and every later block starts by sourcing it by absolute path. The backend
-(step 6) and Metro (step 7) each run as one long-running command in its own background shell.
+functions or traps between calls: step 1 resolves the workspace and writes
+`.cache/ios-env.sh`, which also `cd`s into it; every later block starts by sourcing it by
+absolute path. The backend (step 6) and Metro (step 7) each run as one long-running command
+in its own background shell.
 
-## 1. Checkout and environment
+## 1. Workspace and environment
+
+Workspace precedence is owned by [workspace.md](workspace.md). Do not create a worktree,
+switch branch, fetch or reset when the caller supplied an isolated workspace.
 
 ```bash
 set -euo pipefail
-git fetch origin main
-git worktree add -b <new-branch> ../<repo>-ios-setup origin/main
-cd ../<repo>-ios-setup
-git rev-parse HEAD
+ASSIGNED_WORKSPACE=<assigned-workspace-or-empty>
+CANDIDATE_HEAD=<candidate-head-or-empty>
+WORKSPACE="${ASSIGNED_WORKSPACE:?use the caller assignment or native-start result from workspace.md}"
+test -d "$WORKSPACE"
+git -C "$WORKSPACE" rev-parse --is-inside-work-tree >/dev/null
+cd "$WORKSPACE"
+actual_head="$(git rev-parse HEAD)"
+test -z "$CANDIDATE_HEAD" || test "$actual_head" = "$(git rev-parse "$CANDIDATE_HEAD^{commit}")" || {
+  echo "workspace HEAD $actual_head != candidate $CANDIDATE_HEAD; report it; do not switch" >&2
+  exit 1
+}
 mkdir -p .cache
-{ echo 'set -euo pipefail'; printf 'cd %q\n' "$PWD"; } > .cache/ios-env.sh
+{ echo 'set -euo pipefail'; printf 'cd %q\n' "$PWD"; printf 'export IOS_SOURCE_HEAD=%q\n' "$actual_head"; } > .cache/ios-env.sh
 cat >> .cache/ios-env.sh <<'ENV'
 
 # Repo-specific names, read from the repo's app config, build script and device harness.
@@ -52,6 +63,11 @@ node --version; pnpm --version; ruby --version; pod --version
 grep '^COCOAPODS:' "$IOS_DIR/Podfile.lock"   # must match pod --version
 ```
 
+The recorded standalone path is reused on retries; verify its lifecycle record names this
+run, branch and base. If an assigned path is missing, is not a Git worktree, or is at another
+revision, stop and report instead of creating another checkout. Never fall back to
+`../<repo>-ios-setup`.
+
 `xcode-select -p` must point into `Xcode.app`, not CommandLineTools. The workstation owner
 selects Xcode and accepts its license; do not run `sudo xcodebuild -license` yourself.
 

package/skills/app-dev/ios-foundation/references/workspace.md

@@ -0,0 +1,82 @@
+# iOS workspace lifecycle
+
+The coordinator or caller owns workspace selection. Resolve it once, before any setup stage,
+and record the result. This reference owns only that lifecycle: private caches, Xcode and
+simulator isolation, and backend/Metro cleanup stay in [setup.md](setup.md) and
+[Owned-resource cleanup](../SKILL.md#owned-resource-cleanup).
+
+## Precedence
+
+1. **Assigned workspace and candidate HEAD.** When the caller supplies an isolated workspace
+   and a candidate HEAD, use that workspace and that revision. Do not create a worktree or
+   branch, fetch, reset or switch revisions. Read `git rev-parse HEAD` and report it as the
+   source SHA. If it differs from the candidate HEAD, stop and report the mismatch; never
+   switch the workspace to match.
+2. **Existing owned workspace.** Feature work, fixes, triage and any read-only investigation
+   reuse the workspace this run or unit already owns, with its private caches, Pods and
+   DerivedData. Do not make a second workspace for a retry, a correction or a read-only
+   investigation.
+3. **Standalone fresh setup.** Only when the coordinator reports no usable assignment. Create
+   one managed workspace at
+   `<repo>/.resolve-issues/rush/<run-id>/units/native`. Never create a sibling checkout such
+   as `../<repo>-ios-setup`, and never add a second managed path for a retry.
+
+Android and iOS setup in the same run share that one managed workspace; their private cache
+subdirectories and short-lived processes stay separate.
+
+An assigned path that is missing, is not a Git worktree, or is at another revision is not an
+invitation to substitute a fresh checkout: stop and report it. For triage, name the actual
+checkout and HEAD and confirm it contains the failing code; the repository root or another
+checkout may lag the candidate.
+
+## Record before creating
+
+The bundled `scripts/workspace-runtime` is generated from the shared lifecycle
+engine and ships with this skill. Only for standalone fresh setup, run:
+
+```bash
+node <skill-base-dir>/scripts/workspace-runtime/bin/workspaces.mjs native-start --repo <canonical-root> \
+  --platform ios --target <verified-target-branch> --base <candidate-SHA> --json
+```
+
+The command records root, owner, exact base, branch, workspace and disposable cache
+paths before creating anything. Use its returned `workspace` as `ASSIGNED_WORKSPACE`
+and `sourceSha` as `CANDIDATE_HEAD` in setup. Keep `run` and `runId`; repeat with
+`--run-id <returned-run-id>` and the same base, target and kind for retries. Never
+invoke it inside a coordinator-assigned unit. It never substitutes `origin/main`
+for the requested source or resets an existing workspace.
+For a package below the root, pass `--native-dir <package-root-containing-ios>`.
+Declare other installs or build directories before use with repeated
+`--disposable <exact-workspace-relative-path>`, including package-local `node_modules`.
+
+## Development workspace vs short-lived processes
+
+The workspace, its private caches under `.cache/`, its Pods and DerivedData are development
+resources: retain them across retries and fixes, and keep them private to this workspace.
+Never relocate them to a global cache or share them with a concurrent owner.
+
+Simulators, backend and Metro children, containers and their databases are short-lived: start
+only those the selected checks need and stop only the ones this run started, under the
+existing [cleanup rules](../SKILL.md#owned-resource-cleanup). Never delete a worktree, remove
+a cache with a chmod or `rm` pattern, or use a broad kill or `simctl erase all`.
+
+A read-only investigation does not require a clean environment. Reuse the owned workspace and
+its caches, create only the services the observation needs, and preserve the failed
+environment's evidence. Do not rebuild, reinstall pods or re-provision merely because the
+failure is being investigated.
+
+## Completion
+
+At the end of the assignment, return the workspace, its cache paths and any retained process
+records to the coordinator for final cleanup. The coordinator owns deletion and retention.
+Register the path with the run's cleanup owner so final cleanup can tell a delivered
+standalone run from unfinished or unpublished work.
+
+- A successful, delivered standalone run must not retain an unbounded cache: mark the
+  workspace and its disposable caches for final cleanup. After stopping its owned
+  services, run `node <skill-base-dir>/scripts/workspace-runtime/bin/workspaces.mjs native-finish --run <run> --json`
+  from the owner checkout. This uses the same cleanup engine as issue workflows.
+- Unfinished or unpublished standalone work keeps the workspace and caches for the next
+  attempt; report what is retained and why.
+
+The parent lifecycle record is authoritative for ownership, retention and final cleanup.

package/skills/app-dev/ios-foundation/scripts/workspace-runtime/bin/workspaces.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process'
+import { prepare, cleanup, recover, inventory } from '../workspace-lifecycle.mjs'
+import { nativeStart, nativeFinish } from '../native-workspace.mjs'
+
+const allowed = {
+  prepare: ['run', 'unit', 'revision', 'apply', 'json'],
+  cleanup: ['run', 'unit', 'revision', 'apply', 'json'],
+  recover: ['repo', 'json'],
+  inventory: ['repo', 'root', 'max-entries', 'max-depth', 'json'],
+  'native-start': ['repo', 'run-id', 'base', 'branch', 'target', 'platform', 'kind', 'native-dir', 'disposable', 'json'],
+  'native-finish': ['run', 'json'],
+}
+
+function options(command, args) {
+  if (!Object.hasOwn(allowed, command)) throw new Error('expected prepare, cleanup, recover, inventory, native-start or native-finish')
+  const out = {}
+  for (let index = 0; index < args.length; index++) {
+    const name = args[index].replace(/^--/, '')
+    if (!args[index].startsWith('--') || !allowed[command].includes(name)) throw new Error(`invalid ${command} option: ${args[index]}`)
+    const key = name.replace(/-([a-z])/g, (_, value) => value.toUpperCase())
+    if (Object.hasOwn(out, key) && name !== 'disposable') throw new Error(`duplicate option: --${name}`)
+    if (name === 'apply' || name === 'json') { out[key] = true; continue }
+    const value = args[++index]
+    if (value === undefined || value.startsWith('--')) throw new Error(`--${name} needs a value`)
+    if (name === 'disposable') (out[key] ??= []).push(value)
+    else out[key] = value
+  }
+  for (const key of ['revision', 'maxEntries', 'maxDepth']) {
+    if (out[key] === undefined) continue
+    if (!/^\d+$/.test(out[key]) || !Number.isSafeInteger(Number(out[key]))) throw new Error(`invalid ${key}`)
+    out[key] = Number(out[key])
+  }
+  return out
+}
+
+try {
+  const [command, ...args] = process.argv.slice(2)
+  const opts = options(command, args)
+  let result
+  if (command === 'native-start') result = nativeStart(opts)
+  else if (command === 'native-finish') result = nativeFinish(opts)
+  else if (command === 'prepare') result = prepare(opts)
+  else if (command === 'cleanup') result = cleanup({ ...opts, runGh: (argv) => execFileSync('gh', argv, { encoding: 'utf8', timeout: 30_000, maxBuffer: 4 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] }) })
+  else if (command === 'recover') result = recover(opts)
+  else result = inventory(opts)
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+  process.exitCode = result.ok === false ? 1 : 0
+} catch (error) {
+  process.stderr.write(`${error.message}\n`)
+  process.exitCode = 2
+}

package/skills/app-dev/ios-foundation/scripts/workspace-runtime/native-workspace.mjs

@@ -0,0 +1,239 @@
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+
+const cli = fileURLToPath(new URL('./bin/workspaces.mjs', import.meta.url))
+const git = (cwd, ...args) => execFileSync('git', ['-C', cwd, ...args], { encoding: 'utf8', timeout: 30_000, stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+const component = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(value) && value !== '.' && value !== '..'
+
+function stat(path) {
+  try { return lstatSync(path) } catch (error) { if (error.code === 'ENOENT') return null; throw error }
+}
+
+function noLinks(root, path) {
+  const rel = relative(root, path)
+  if (rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel)) throw new Error('workspace path escapes its repository')
+  let current = root
+  for (const part of rel.split(sep).filter(Boolean)) {
+    current = join(current, part)
+    if (stat(current)?.isSymbolicLink()) throw new Error(`symlink in managed path: ${current}`)
+  }
+}
+
+// This lock owns the plan, including initial creation. The engine independently locks
+// workspace operations; its shorter lock cannot protect our read/modify/write cycle.
+function withOwner(repo, run, operation) {
+  const locks = join(dirname(run), '.native-locks')
+  const lock = join(locks, basename(run))
+  noLinks(repo, run)
+  noLinks(repo, lock)
+  mkdirSync(locks, { recursive: true })
+  try { mkdirSync(lock) } catch (error) {
+    if (error.code !== 'EEXIST') throw error
+    let owner = 'unknown owner'
+    try { owner = `owner PID ${JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8')).pid ?? 'unknown'}` } catch { /* Unknown owners also block. */ }
+    throw new Error(`native run is locked at ${lock} (${owner}); locks are never reclaimed by age`)
+  }
+  try {
+    writeFileSync(join(lock, 'owner.json'), `${JSON.stringify({ pid: process.pid, run, at: new Date().toISOString() })}\n`, { flag: 'wx', mode: 0o600 })
+    return operation()
+  } finally {
+    try { unlinkSync(join(lock, 'owner.json')) } catch (error) {
+      if (error.code !== 'ENOENT') throw error
+    } finally {
+      rmdirSync(lock)
+      try { rmdirSync(locks) } catch (error) { if (!['ENOTEMPTY', 'ENOENT', 'EEXIST'].includes(error.code)) throw error }
+    }
+  }
+}
+
+function planStore(repo, run) {
+  const file = join(run, 'task-plan.json')
+  const read = () => {
+    noLinks(repo, file)
+    return stat(file) ? readFileSync(file, 'utf8') : null
+  }
+  let expected = read()
+  const plan = expected === null ? null : JSON.parse(expected)
+  let revision = plan?.planRevision ?? -1
+  return {
+    plan,
+    save(next) {
+      if (read() !== expected || (expected !== null && JSON.parse(expected).planRevision !== revision)) {
+        throw new Error('native plan revision/content changed; refusing to overwrite another owner')
+      }
+      next.planRevision = revision + 1
+      const text = `${JSON.stringify(next, null, 2)}\n`
+      const temp = `${file}.${randomUUID()}.tmp`
+      try {
+        writeFileSync(temp, text, { flag: 'wx', mode: 0o600 })
+        if (read() !== expected) throw new Error('native plan changed before persist; refusing to overwrite another owner')
+        renameSync(temp, file)
+        expected = text
+        revision = next.planRevision
+      } finally {
+        if (stat(temp)) unlinkSync(temp)
+      }
+    },
+  }
+}
+
+function ownedPlan(plan, repo, run) {
+  const unit = plan?.units?.[0]
+  if (plan?.skill !== 'native-setup' || plan.workspaceLifecycle !== 1 || plan.repoRoot !== repo || plan.runDir !== run ||
+      !Number.isSafeInteger(plan.planRevision) || plan.planRevision < 0 || plan.units?.length !== 1 || unit?.id !== 'native' ||
+      unit.workspace !== join(run, 'units', 'native') || unit.lifecycle?.version !== 1 ||
+      !['worktree', 'clone'].includes(unit.lifecycle.workspace?.kind) || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(unit.lifecycle.workspace?.baseSha ?? '') ||
+      unit.base !== unit.lifecycle.workspace.baseSha || !Array.isArray(unit.lifecycle.resources)) {
+    throw new Error('not an owned standalone native run; refusing to replace its record')
+  }
+  git(repo, 'check-ref-format', '--branch', plan.targetBranch)
+  git(repo, 'check-ref-format', '--branch', unit.branch)
+  noLinks(repo, unit.workspace)
+  return unit
+}
+
+function relativePath(value, label, allowRoot = false) {
+  if (allowRoot && value === '.') return value
+  if (typeof value !== 'string' || !value || isAbsolute(value) || value.includes('\\') || /[\0*?\[\]]/.test(value) ||
+      value.split('/').some((part) => !part || part === '.' || part === '..' || part === '.git' || part === '.resolve-issues')) {
+    throw new Error(`${label} must be an exact relative path without .., symlinks, or managed roots`)
+  }
+  return value
+}
+
+function resourcePaths(repo, workspace, platform, nativeDir, disposable) {
+  relativePath(nativeDir, '--native-dir', true)
+  if (!Array.isArray(disposable)) throw new Error('disposable must be an array of workspace-relative paths')
+  const paths = [...new Set(['.cache', 'node_modules',
+    ...(platform === 'ios' ? ['ios/Pods'] : ['android/.gradle', 'android/build', 'android/app/build']).map((path) => nativeDir === '.' ? path : `${nativeDir}/${path}`),
+    ...disposable.map((path) => relativePath(path, '--disposable'))])]
+  noLinks(repo, join(repo, nativeDir))
+  noLinks(repo, join(workspace, nativeDir))
+  for (const path of paths) {
+    noLinks(repo, join(repo, path))
+    noLinks(repo, join(workspace, path))
+  }
+  return paths
+}
+
+function engine(args, repo) {
+  const result = spawnSync(process.execPath, [cli, ...args, '--json'], { cwd: repo, encoding: 'utf8', timeout: 120_000, maxBuffer: 8 * 1024 * 1024 })
+  let value
+  try { value = JSON.parse(result.stdout) } catch { /* Report the failed command below. */ }
+  if (result.status === 0 || (result.status === 1 && value?.action === 'retain' && (value.lifecycle || value.nextLifecycle))) return value
+  throw new Error(result.stderr?.trim() || result.stdout?.trim() || result.error?.message || 'workspace operation failed')
+}
+
+function returnedLifecycle(result) {
+  const lifecycle = result?.lifecycle ?? result?.nextLifecycle
+  if (!lifecycle || lifecycle.version !== 1) throw new Error('workspace helper returned no lifecycle transition; the recorded intent remains recoverable')
+  return lifecycle
+}
+
+export function nativeStart({ repo: input, runId, base, branch, target, platform, kind, nativeDir, disposable = [] }) {
+  if (!input || !['android', 'ios'].includes(platform) || (kind !== undefined && !['worktree', 'clone'].includes(kind))) throw new Error('native-start requires --repo and --platform android|ios; --kind is worktree or clone')
+  const repo = realpathSync(resolve(input))
+  if (realpathSync(git(repo, 'rev-parse', '--show-toplevel')) !== repo) throw new Error('--repo must name the owning checkout root')
+  const id = runId ?? `native-${new Date().toISOString().replace(/[^0-9]/g, '')}-${process.pid}`
+  if (!component(id)) throw new Error('invalid native run id')
+  const run = join(repo, '.resolve-issues', 'rush', id)
+  return withOwner(repo, run, () => {
+    const store = planStore(repo, run)
+    let plan = store.plan
+    if (!plan && stat(run)) throw new Error('existing run has no ownership record; refusing to adopt it')
+    let unit
+    if (plan) {
+      unit = ownedPlan(plan, repo, run)
+      if ((base !== undefined && git(repo, 'rev-parse', '--verify', `${base}^{commit}`) !== unit.base) ||
+          (target !== undefined && target !== plan.targetBranch) || (kind !== undefined && kind !== unit.lifecycle.workspace.kind) ||
+          (branch !== undefined && branch !== unit.branch) || (nativeDir !== undefined && nativeDir !== (unit.nativeDir ?? '.'))) {
+        throw new Error('existing native run belongs to a different setup; refusing to replace it')
+      }
+      nativeDir = unit.nativeDir ?? '.'
+    } else {
+      const baseSha = git(repo, 'rev-parse', '--verify', `${base ?? 'HEAD'}^{commit}`)
+      if (!target) {
+        try { target = git(repo, 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD').replace(/^origin\//, '') } catch { throw new Error('record the repository target branch with --target; origin/HEAD is unavailable') }
+      }
+      branch ??= `native/${id}`
+      kind ??= 'worktree'
+      nativeDir ??= '.'
+      git(repo, 'check-ref-format', '--branch', target)
+      git(repo, 'check-ref-format', '--branch', branch)
+      unit = { id: 'native', title: 'Standalone native setup', workspace: join(run, 'units', 'native'), branch, base: baseSha, nativeDir, disposable: [], status: 'in-flight', stage: 'implement', worker: null,
+        lifecycle: { version: 1, workspace: { kind, state: 'preparing', baseSha }, resources: [], cleanup: { state: 'pending' } } }
+      plan = { skill: 'native-setup', workspaceLifecycle: 1, repoRoot: repo, runDir: run, targetBranch: target, planRevision: 0, units: [unit] }
+    }
+    if (unit.lifecycle.cleanup?.state === 'complete') throw new Error('this setup was cleaned; start a new run rather than recreating a used workspace')
+    if (!Array.isArray(disposable) || (unit.disposable !== undefined && !Array.isArray(unit.disposable))) throw new Error('disposable must be an array of workspace-relative paths')
+    const extras = [...new Set([...(unit.disposable ?? []), ...disposable])]
+    const paths = resourcePaths(repo, unit.workspace, platform, nativeDir, extras)
+    let changed = !store.plan || unit.nativeDir === undefined || JSON.stringify(unit.disposable) !== JSON.stringify(extras)
+    unit.nativeDir = nativeDir
+    unit.disposable = extras
+    for (const item of paths) {
+      const path = join(unit.workspace, item)
+      if (unit.lifecycle.resources.some((r) => r.path === path)) continue
+      unit.lifecycle.resources.push({ path, role: 'scratch', kind: 'directory', disposable: true, state: 'preparing' })
+      changed = true
+    }
+    if (!store.plan) mkdirSync(run)
+    if (changed) store.save(plan)
+    const result = engine(['prepare', '--run', run, '--unit', 'native', '--revision', String(plan.planRevision), '--apply'], repo)
+    unit.lifecycle = returnedLifecycle(result)
+    store.save(plan)
+    return { ...result, run, runId: id, workspace: unit.workspace, nativeDir, disposable: extras, sourceSha: git(unit.workspace, 'rev-parse', 'HEAD'), planRevision: plan.planRevision }
+  })
+}
+
+export function nativeFinish({ run: input }) {
+  if (!input) throw new Error('native-finish requires --run')
+  const run = resolve(input)
+  const repo = realpathSync(join(run, '..', '..', '..'))
+  if (!component(basename(run)) || run !== join(repo, '.resolve-issues', 'rush', basename(run))) throw new Error('not an owned standalone native run')
+  noLinks(repo, run)
+  if (!stat(run)?.isDirectory()) throw new Error('native run does not exist')
+  return withOwner(repo, run, () => {
+    const store = planStore(repo, run)
+    const plan = store.plan
+    const unit = ownedPlan(plan, repo, run)
+    // Completed and interrupted removals still go through the engine's postcondition
+    // checks, including owned resources outside the workspace and cleanup receipts.
+    const completeCleanup = () => {
+      const result = engine(['cleanup', '--run', run, '--unit', 'native', '--revision', String(plan.planRevision), '--apply'], repo)
+      const lifecycle = returnedLifecycle(result)
+      if (result.ok !== false && (lifecycle.cleanup?.state !== 'complete' || existsSync(unit.workspace) || lifecycle.resources.some((r) => existsSync(r.path)))) {
+        throw new Error('cleanup has not reached its postconditions; the recorded intent remains recoverable')
+      }
+      unit.lifecycle = lifecycle
+      store.save(plan)
+      return { ...result, run, planRevision: plan.planRevision }
+    }
+    if (unit.lifecycle.cleanup?.state === 'complete' || (!existsSync(unit.workspace) && unit.lifecycle.cleanup?.state === 'applying')) return completeCleanup()
+    const headSha = git(unit.workspace, 'rev-parse', 'HEAD')
+    const remote = git(repo, 'remote', 'get-url', 'origin')
+    git(unit.workspace, 'fetch', '--no-tags', '--', remote, `+refs/heads/${plan.targetBranch}:refs/remotes/native-delivery/${plan.targetBranch}`)
+    const targetRef = `refs/remotes/native-delivery/${plan.targetBranch}`
+    let landed = false
+    try { git(unit.workspace, 'merge-base', '--is-ancestor', headSha, targetRef); landed = true } catch (error) {
+      if (error.status !== 1) throw error
+    }
+    if (!landed) {
+      unit.headSha = headSha
+      const reason = 'native source has not landed on the recorded remote target; retain its environment'
+      unit.lifecycle.cleanup = { state: 'retained', headSha, reason }
+      store.save(plan)
+      return { ok: false, action: 'retain', outcome: 'retained', reason, run, lifecycle: unit.lifecycle, planRevision: plan.planRevision }
+    }
+    unit.headSha = headSha
+    unit.mergeSha = headSha
+    unit.status = 'succeeded'
+    unit.delivery = 'merged'
+    unit.lifecycle.cleanup = { state: 'applying', headSha }
+    store.save(plan)
+    return completeCleanup()
+  })
+}