@1aboveio/skills 1.0.9 → 1.0.11

package/skills/engineering/harness-runtime/SKILL.md

@@ -3,7 +3,7 @@ name: harness-runtime
 description: Internal import-only library shared by first-party engineering packages. Not a workflow skill; never select or invoke it as a user capability.
 disable-model-invocation: true
 user-invocable: false
-release-version: 0.44.0
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Harness Runtime
@@ -17,3 +17,5 @@ This support-only runtime package exposes shared programmatic contracts plus can
 - `index.mjs` exports neutral constructors plus pure question planning and response normalization.
 - `discover-models.mjs` enumerates model evidence; `model-catalog.mjs` manages per-harness classifications.
 - `references/model-catalog.md` documents catalog policy; `bin/` contains the installed command wrappers.
+- `workspace-lifecycle.mjs` and `bin/workspaces.mjs` own workspace preparation and reclamation;
+  read [references/workspaces.md](references/workspaces.md) for standalone native setup.

package/skills/engineering/harness-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/engineering/harness-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()
+  })
+}

package/skills/engineering/harness-runtime/references/workspaces.md

@@ -0,0 +1,78 @@
+# Owned Workspaces
+
+The same lifecycle engine serves `resolve-issues` and standalone native setup.
+It creates one recorded workspace, reuses it, and removes only owned, delivered,
+idle environments. It never deletes legacy project folders by age or naming pattern.
+
+## Assigned Work
+
+An orchestrator supplies its prepared workspace and candidate SHA. Use both as
+given. Do not run `native-start` inside an assigned unit, create a second checkout,
+switch branches or reset the source. Return resource paths to that orchestrator;
+only it writes its task plan and decides when delivery permits cleanup.
+
+Keep mutable caches private and declare their exact disposable paths before use.
+An ignored file is not automatically disposable. Shared SDKs and other projects
+are never owned resources of a unit.
+
+## Standalone Setup
+
+Resolve this installed runtime from the caller's selected installation, not a
+filesystem search or another cached version. With no assigned or existing owned
+workspace, run:
+
+```bash
+node <harness-runtime>/bin/workspaces.mjs native-start --repo <canonical-repo-root> \
+  --platform android --target <verified-target-branch> --base <candidate-SHA> --json
+```
+
+For iOS, use `--platform ios`. For a kernel-confined Git-mutating worker, choose
+`--kind clone` before preparing; never disable confinement to use a linked tree.
+For a native package below the root, pass `--native-dir apps/native` (the package
+root containing `ios/` or `android/`). Register other outputs before installation
+with repeated `--disposable <workspace-relative-directory>`, including every
+package-local `node_modules` directory the install will create. No glob discovery
+or ignored-file heuristic establishes disposal authority.
+The owner root can remain dirty: creation uses the recorded commit, not its local
+uncommitted files. The command does not fetch or change the owner checkout.
+
+Read the JSON result. `run`, `runId`, `workspace`, `sourceSha`, and `planRevision`
+identify the assignment. Pass `workspace` and `sourceSha` to native setup. Reuse
+the returned `runId` with `--run-id` and the same base, target and kind for retries
+and for adding the other platform to the same unit. Never create a run per attempt.
+
+`native-start` records intent in
+`<repo>/.resolve-issues/rush/<run-id>/task-plan.json` before preparation. That small
+record is the standalone owner's authority, not a second manifest for an issue
+workflow. The command records the workspace and platform-specific disposable
+caches, then persists the lifecycle engine's returned identities. A conflicting
+or missing previously used workspace is reported, never reset or recreated.
+
+## Finish And Recover
+
+Stop the assignment's native services, devices and containers through their own
+owners, then run from the owner checkout, not the workspace being removed:
+
+```bash
+node <harness-runtime>/bin/workspaces.mjs native-finish --run <returned-run-path> --json
+```
+
+The source must be on the recorded remote target. Dirty source, unpublished work,
+unknown ignored files, required evidence inside a disposable path, or live use
+retains the complete environment with a reason. A successful removal preserves
+the small plan and cleanup receipt; it does not leave installed dependencies and
+build caches. Retention is not successful cleanup. Keep the returned record and
+report its reason without inventing a passing validation result.
+
+An interrupted operation remains in the same plan. Inspect it without deleting:
+
+```bash
+node <harness-runtime>/bin/workspaces.mjs recover --repo <canonical-repo-root> --json
+node <harness-runtime>/bin/workspaces.mjs inventory --repo <canonical-repo-root> \
+  --root <explicit-legacy-workspace-root> --max-entries 5000 --max-depth 8 --json
+```
+
+Discovery does not activate a workflow, adopt a legacy directory or authorize
+deletion. Never turn an unknown or missing path into a completed cleanup result.
+Standalone commands hold a per-run owner lock across plan updates and engine calls;
+they refuse concurrent owners and never reclaim an unknown lock by age.