orizu 0.5.38 → 0.5.39

package/src/artifacts-git-runtime.ts

@@ -1,13 +1,16 @@
 import { spawn } from 'node:child_process'
-import { chmod, mkdir, rm, writeFile } from 'node:fs/promises'
+import { rmSync } from 'node:fs'
+import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import type { Writable } from 'node:stream'
 
 const ARTIFACT_TOKEN_BODY = /^[^\s\u0000-\u001f\u007f]{16,1024}$/
 const ARTIFACT_TOKEN_ADVISORY_SUFFIX = '?expires='
 const ARTIFACT_TOKEN_BARE_BODY = /art_v1_[0-9a-fA-F]{40}/
 const DEFAULT_GIT_TIMEOUT_MS = 30_000
 const GIT_TERMINATION_GRACE_MS = 1_000
+/** Names the one-use key file, set on the git process that needs it and nowhere else. */
+const GIT_KEY_FILE_ENV = 'ORIZU_GIT_KEY_FILE'
 const GIT_CONTEXT_ENV_KEYS = [
   'GIT_DIR',
   'GIT_WORK_TREE',
@@ -118,7 +121,8 @@ export async function createEphemeralAskPass(
 case "$1" in
   *sername*) printf '%s\\n' x ;;
   *assword*)
-    IFS= read -r password <&3 || exit 1
+    [ -n "$${GIT_KEY_FILE_ENV}" ] || exit 1
+    IFS= read -r password < "$${GIT_KEY_FILE_ENV}" || exit 1
     [ -n "$password" ] || exit 1
     printf '%s\\n' "$password"
     ;;
@@ -204,10 +208,70 @@ function signalGitProcess(child: ReturnType<typeof spawn>, signal: NodeJS.Signal
   }
 }
 
-export const defaultGitRunner: GitRunner = (
-  args,
-  { cwd, auth, env: suppliedEnv, commitIdentityEnv, timeoutMs = DEFAULT_GIT_TIMEOUT_MS, signal }
-) =>
+/** Key folders this process holds right now. An abrupt end of the process
+ * skips the runner's own cleanup, so they are also removed, best effort, on
+ * exit, and on a termination signal that ends the process. A script that
+ * handles the signal itself keeps its keys: its running command may still need
+ * them, and the exit listener covers it later. SIGKILL cannot be caught: a
+ * folder it leaves behind holds a key that still expires on its own. */
+const liveKeyDirs = new Set<string>()
+let isExitCleanupInstalled = false
+// SIGHUP and SIGQUIT run no exit handlers either; operator scripts run over SSH.
+const TERMINATION_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT'] as const
+
+function removeLiveKeyDirs(): void {
+  for (const dir of liveKeyDirs) {
+    try {
+      rmSync(dir, { recursive: true, force: true })
+    } catch {
+      // Best effort: the process is ending.
+    }
+  }
+  liveKeyDirs.clear()
+}
+
+function handleTerminationSignal(signal: NodeJS.Signals): void {
+  // Another listener decides whether the process ends; leave the keys to it.
+  if (process.listenerCount(signal) !== 1) return
+  removeLiveKeyDirs()
+  // End the way the signal would have without this listener.
+  process.off(signal, handleTerminationSignal)
+  process.kill(process.pid, signal)
+}
+
+function installExitCleanup(): void {
+  if (isExitCleanupInstalled) return
+  isExitCleanupInstalled = true
+  process.on('exit', removeLiveKeyDirs)
+  for (const signal of TERMINATION_SIGNALS) process.on(signal, handleTerminationSignal)
+}
+
+/** Runs one git command. With auth, the key goes in a 0600 file inside a
+ * fresh 0700 folder, named to that git process only by ORIZU_GIT_KEY_FILE.
+ * Askpass reads it from there. The folder is removed when the command
+ * settles, however it ends: success, failure, timeout or cancel; and if this
+ * process ends first, on its way out (see liveKeyDirs). */
+export const defaultGitRunner: GitRunner = async (args, options) => {
+  if (!options.auth) return runGitProcess(args, options, null)
+  installExitCleanup()
+  const keyDir = await mkdtemp(join(tmpdir(), 'orizu-git-key-'))
+  liveKeyDirs.add(keyDir)
+  try {
+    await chmod(keyDir, 0o700)
+    const keyFile = join(keyDir, 'key')
+    await writeFile(keyFile, `${options.auth.token}\n`, { mode: 0o600, flag: 'wx' })
+    return await runGitProcess(args, options, keyFile)
+  } finally {
+    await rm(keyDir, { recursive: true, force: true })
+    liveKeyDirs.delete(keyDir)
+  }
+}
+
+const runGitProcess = (
+  args: string[],
+  { cwd, auth, env: suppliedEnv, commitIdentityEnv, timeoutMs = DEFAULT_GIT_TIMEOUT_MS, signal }: GitRunOptions,
+  keyFile: string | null
+): Promise<GitCommandResult> =>
   new Promise((resolve, reject) => {
     if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
       reject(new Error('Git timeout must be a positive integer'))
@@ -225,7 +289,7 @@ export const defaultGitRunner: GitRunner = (
       return
     }
     const baseEnv = auth
-      ? buildGitAuthEnvironment(auth, suppliedEnv)
+      ? { ...buildGitAuthEnvironment(auth, suppliedEnv), ...(keyFile ? { [GIT_KEY_FILE_ENV]: keyFile } : {}) }
       : buildUnauthenticatedGitEnvironment(suppliedEnv)
     let env = baseEnv
     if (commitIdentityEnv) {
@@ -237,7 +301,7 @@ export const defaultGitRunner: GitRunner = (
       cwd,
       env,
       detached: process.platform !== 'win32',
-      stdio: auth ? ['ignore', 'pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+      stdio: ['ignore', 'pipe', 'pipe'],
     })
     let stdout = ''
     let stderr = ''
@@ -314,28 +378,6 @@ export const defaultGitRunner: GitRunner = (
     child.on('close', (code) => {
       finish(termination === 'timeout' ? 124 : termination === 'cancelled' ? 130 : (code ?? 1))
     })
-
-    if (auth) {
-      const credentialPipe = child.stdio[3] as Writable | null
-      if (!credentialPipe) {
-        fail(new Error('Could not establish one-use Git credential pipe'))
-        return
-      }
-      credentialPipe.on('error', () => {
-        /* EPIPE if Git fails before auth. */
-      })
-      if (termination) {
-        credentialPipe.destroy()
-        return
-      }
-      try {
-        credentialPipe.end(`${auth.token}\n`)
-      } catch (error) {
-        fail(
-          error instanceof Error ? error : new Error('Could not write the one-use Git credential')
-        )
-      }
-    }
   })
 
 export async function gitOk(

package/src/artifacts-session-merge.ts

@@ -0,0 +1,253 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import {
+  defaultGitRunner,
+  gitOk,
+  redactSecrets,
+  revParse,
+  type GitAuth,
+  type GitRunner,
+} from './artifacts-git-runtime.js'
+
+/**
+ * The publisher's git step (ORI-2279): merge a session copy into the team
+ * copy, ask for permission, then push with compare-and-swap and read back.
+ *
+ * Runs in a server-owned process with `git` on PATH (the coordinator's merge
+ * job), never in an agent's sandbox. It reads no environment and no
+ * database: the caller's callbacks carry the permission answer and the
+ * one-time team-copy write key.
+ */
+
+const SESSION_MERGE_MAX_ATTEMPTS = 3
+
+const CANONICAL_TRACKING_REF = 'refs/remotes/orizu-canonical/head'
+const SOURCE_TRACKING_REF = 'refs/remotes/orizu-source/head'
+
+interface SessionMergeEndpoint {
+  readonly remote: string
+  /** Read access. Omitted only for local remotes in tests. */
+  readonly auth?: GitAuth
+}
+
+interface PreparedSessionMerge {
+  readonly previousCanonicalSha: string
+  readonly sourceSha: string
+  readonly mergeSha: string
+  readonly attempt: number
+  /** The merge folder: both copies' fetched objects plus the merge commit. */
+  readonly worktree: string
+}
+
+type SessionMergePushResult = 'pushed' | 'stale'
+
+export interface PublishSessionMergeInput {
+  /** A writable folder; each attempt merges in its own temporary subfolder. */
+  readonly root: string
+  readonly canonical: SessionMergeEndpoint
+  readonly source: SessionMergeEndpoint
+  readonly canonicalRef: string
+  readonly sourceRef: string
+  /** The session head the publish was approved for. */
+  readonly expectedSourceSha: string
+  readonly commitMessage: string
+  readonly commitIdentityEnv: Readonly<Record<string, string>>
+  /** The final permission check, asked after every merge and before any write. */
+  readonly authorize: (merge: PreparedSessionMerge) => Promise<boolean>
+  /**
+   * Mints the one-time team-copy write key, runs `push` once with it, then
+   * revokes it. `undefined` is allowed only for local remotes in tests.
+   */
+  readonly withCanonicalWrite: (
+    push: (auth: GitAuth | undefined) => Promise<SessionMergePushResult>
+  ) => Promise<SessionMergePushResult>
+  readonly timeoutMs?: number
+  readonly signal?: AbortSignal
+  readonly runGit?: GitRunner
+}
+
+export type PublishSessionMergeResult =
+  | {
+      readonly kind: 'merged'
+      readonly previousCanonicalSha: string
+      readonly sourceSha: string
+      readonly mergeSha: string
+      readonly attempts: number
+    }
+  | {
+      /** The session head is already in the team copy: nothing to push. */
+      readonly kind: 'already_merged'
+      readonly canonicalSha: string
+      readonly sourceSha: string
+    }
+  | {
+      readonly kind: 'conflict'
+      readonly files: readonly string[]
+      readonly canonicalSha: string
+      readonly sourceSha: string
+    }
+  | { readonly kind: 'denied' }
+  | { readonly kind: 'race_lost'; readonly attempts: number }
+
+type Preparation =
+  | { readonly kind: 'merge'; readonly merge: PreparedSessionMerge }
+  | Extract<PublishSessionMergeResult, { kind: 'already_merged' | 'conflict' }>
+
+export async function publishSessionMerge(
+  input: PublishSessionMergeInput
+): Promise<PublishSessionMergeResult> {
+  const runGit = input.runGit ?? defaultGitRunner
+  for (let attempt = 1; attempt <= SESSION_MERGE_MAX_ATTEMPTS; attempt += 1) {
+    const worktree = await mkdtemp(join(input.root, 'session-merge-'))
+    try {
+      const prepared = await prepareMerge(input, runGit, worktree, attempt)
+      if (prepared.kind !== 'merge') return prepared
+      if (!(await input.authorize(prepared.merge))) return { kind: 'denied' }
+      const pushed = await input.withCanonicalWrite((auth) =>
+        pushMerge(input, runGit, worktree, prepared.merge, auth)
+      )
+      if (pushed === 'stale') continue
+      await readBack(input, runGit, worktree, prepared.merge.mergeSha)
+      return {
+        kind: 'merged',
+        previousCanonicalSha: prepared.merge.previousCanonicalSha,
+        sourceSha: prepared.merge.sourceSha,
+        mergeSha: prepared.merge.mergeSha,
+        attempts: attempt,
+      }
+    } finally {
+      await rm(worktree, { recursive: true, force: true })
+    }
+  }
+  return { kind: 'race_lost', attempts: SESSION_MERGE_MAX_ATTEMPTS }
+}
+
+async function prepareMerge(
+  input: PublishSessionMergeInput,
+  runGit: GitRunner,
+  worktree: string,
+  attempt: number
+): Promise<Preparation> {
+  await gitOk(runGit, ['init', '-q'], { cwd: worktree }, 'initialise merge folder')
+  await fetchInto(input, runGit, worktree, input.canonical, input.canonicalRef, CANONICAL_TRACKING_REF)
+  await fetchInto(input, runGit, worktree, input.source, input.sourceRef, SOURCE_TRACKING_REF)
+  const canonicalSha = await revParse(runGit, worktree, CANONICAL_TRACKING_REF)
+  const sourceSha = await revParse(runGit, worktree, SOURCE_TRACKING_REF)
+  if (sourceSha !== input.expectedSourceSha) {
+    throw new Error('Session copy moved since the publish was approved')
+  }
+  if (await isAncestor(runGit, worktree, sourceSha, canonicalSha)) {
+    return { kind: 'already_merged', canonicalSha, sourceSha }
+  }
+
+  await gitOk(
+    runGit,
+    ['checkout', '-q', '--detach', canonicalSha],
+    { cwd: worktree },
+    'check out the team copy head'
+  )
+  const merge = await runGit(['merge', '--no-ff', '--no-edit', '-m', input.commitMessage, sourceSha], {
+    cwd: worktree,
+    commitIdentityEnv: input.commitIdentityEnv,
+  })
+  if (merge.exitCode === 1) {
+    const unmerged = await gitOk(
+      runGit,
+      ['diff', '--name-only', '--diff-filter=U', '-z'],
+      { cwd: worktree },
+      'list conflicted files'
+    )
+    const files = unmerged.split('\u0000').filter(Boolean)
+    if (files.length > 0) return { kind: 'conflict', files, canonicalSha, sourceSha }
+  }
+  if (merge.exitCode !== 0) {
+    throw new Error(`merge session into team copy failed: ${(merge.stderr || merge.stdout).trim()}`)
+  }
+
+  const mergeSha = await revParse(runGit, worktree, 'HEAD')
+  const parents = (
+    await gitOk(runGit, ['rev-list', '--parents', '-n', '1', mergeSha], { cwd: worktree }, 'inspect merge parents')
+  )
+    .split(/\s+/)
+    .slice(1)
+  if (parents.length !== 2 || parents[0] !== canonicalSha || parents[1] !== sourceSha) {
+    throw new Error('Merge did not keep the team head and session head as its parents')
+  }
+  return { kind: 'merge', merge: { previousCanonicalSha: canonicalSha, sourceSha, mergeSha, attempt, worktree } }
+}
+
+async function pushMerge(
+  input: PublishSessionMergeInput,
+  runGit: GitRunner,
+  worktree: string,
+  merge: PreparedSessionMerge,
+  auth: GitAuth | undefined
+): Promise<SessionMergePushResult> {
+  // The lease is the team head this merge was built on, not whatever the
+  // remote holds now: if another publish landed after our fetch, the push is
+  // refused ("stale info") and the caller merges again on the new head.
+  const result = await runGit(
+    [
+      'push',
+      '--porcelain',
+      `--force-with-lease=${input.canonicalRef}:${merge.previousCanonicalSha}`,
+      input.canonical.remote,
+      `${merge.mergeSha}:${input.canonicalRef}`,
+    ],
+    { cwd: worktree, auth, timeoutMs: input.timeoutMs, signal: input.signal }
+  )
+  if (result.exitCode === 0) return 'pushed'
+  const output = `${result.stdout}\n${result.stderr}`
+  if (!result.timedOut && !result.cancelled && /\(stale info\)/.test(output)) return 'stale'
+  const detail = redactSecrets(output.trim(), auth ? [auth.token] : [])
+  throw new Error(`push merge to team copy failed: ${detail}`)
+}
+
+/** Proves the push landed: the team head is the merge, or a later commit containing it. */
+async function readBack(
+  input: PublishSessionMergeInput,
+  runGit: GitRunner,
+  worktree: string,
+  mergeSha: string
+): Promise<void> {
+  const listed = await gitOk(
+    runGit,
+    ['ls-remote', '--refs', input.canonical.remote, input.canonicalRef],
+    { cwd: worktree, auth: input.canonical.auth, timeoutMs: input.timeoutMs, signal: input.signal },
+    'read back the team copy head'
+  )
+  const [head, ref] = listed.split(/\s+/)
+  if (ref !== input.canonicalRef || !/^[0-9a-f]{40}$/.test(head ?? '')) {
+    throw new Error('Team copy read-back returned an unexpected answer')
+  }
+  if (head === mergeSha) return
+  await fetchInto(input, runGit, worktree, input.canonical, input.canonicalRef, CANONICAL_TRACKING_REF)
+  const fetched = await revParse(runGit, worktree, CANONICAL_TRACKING_REF)
+  if (!(await isAncestor(runGit, worktree, mergeSha, fetched))) {
+    throw new Error('Team copy read-back does not contain the pushed merge')
+  }
+}
+
+async function fetchInto(
+  input: PublishSessionMergeInput,
+  runGit: GitRunner,
+  worktree: string,
+  endpoint: SessionMergeEndpoint,
+  ref: string,
+  trackingRef: string
+): Promise<void> {
+  await gitOk(
+    runGit,
+    ['fetch', '-q', '--no-tags', endpoint.remote, `+${ref}:${trackingRef}`],
+    { cwd: worktree, auth: endpoint.auth, timeoutMs: input.timeoutMs, signal: input.signal },
+    `fetch ${ref}`
+  )
+}
+
+async function isAncestor(runGit: GitRunner, cwd: string, ancestor: string, descendant: string): Promise<boolean> {
+  const result = await runGit(['merge-base', '--is-ancestor', ancestor, descendant], { cwd })
+  if (result.exitCode === 0) return true
+  if (result.exitCode === 1) return false
+  throw new Error(`check ancestry failed: ${result.stderr.trim()}`)
+}

package/src/dataset-append-workflow.ts

@@ -0,0 +1,205 @@
+import { statSync } from 'node:fs'
+import { extname } from 'node:path'
+
+import { Context, Effect, Result, Schema } from 'effect'
+
+import { parseDatasetFile } from './file-parser.js'
+import { datasetTransferTimeoutMs } from './dataset-transfer-policy.js'
+import { authedFetch } from './http.js'
+import { streamJsonlRowChunks } from './jsonl-stream.js'
+import { sanitizeTerminalText } from './json-response.js'
+
+type Rows = ReadonlyArray<Readonly<Record<string, unknown>>>
+export interface DatasetAppendInput {
+  datasetId: string
+  file: string
+}
+interface AppendIo {
+  json: boolean
+  print: (message: string) => void
+}
+type Outcome = 'rejected' | 'unknown' | 'not_sent'
+interface FailedChunk { index: number; inputRows: number; outcome: Outcome }
+interface Progress {
+  datasetId: string | null
+  confirmedRows: number
+  confirmedChunks: number
+  chunk: FailedChunk | null
+}
+class AppendFailure extends Error {
+  readonly _tag = 'AppendFailure'
+  constructor(message: string, readonly outcome: Outcome) { super(sanitizeTerminalText(message)) }
+}
+
+const Acknowledgement = Schema.Struct({
+  dataset: Schema.Struct({ id: Schema.String, name: Schema.String, rowCount: Schema.Natural }),
+  appendedCount: Schema.Natural,
+})
+type Acknowledgement = typeof Acknowledgement.Type
+const RowsSchema = Schema.Array(Schema.Record(Schema.String, Schema.Unknown))
+const appendTransport = Context.Service<{
+  append: (datasetId: string, rows: Rows) => Effect.Effect<Acknowledgement, AppendFailure>
+}>('orizu/cli/DatasetAppendTransport')
+
+// Only responses naming an existing rows-route rejection establish a known
+// refusal. A proxy body or a lost body is not evidence that nothing committed.
+function isKnownRefusal(message: string, status: number): boolean {
+  // These exact templates come from artifact preparation before the append RPC.
+  // Status alone or an arbitrary artifact/proxy prefix cannot prove rejection.
+  if (status === 400 && (
+    message === 'Dataset row id cannot be stored as an artifact' ||
+    /^Invalid dataset row artifact reference at .+$/.test(message) ||
+    /^Dataset row artifact ref at .+ (?:is nested; v1 supports top-level fields only|was not issued by this server|belongs to a different project|has been deleted|has not been finalized|is expired|was issued to a different user|is not attachable|does not match server metadata|targets a different (?:dataset|field|row id))$/.test(message)
+  )) return true
+  if (status === 413 && (
+    /^Dataset row .+ exceeds 65536 bytes after externalizing top-level fields$/.test(message) ||
+    /^.+ exceeds (?:26214400 bytes before compression|10485760 bytes after compression)$/.test(message)
+  )) return true
+  return /^(Missing bearer token|Unauthorized|Dataset not found|Only project curators\/admins can modify dataset rows|Dataset is locked and cannot be mutated|Duplicate row ids provided|One or more row ids already exist in this dataset|rows must contain at least one item|rows\[\d+\] must be an object|Dataset row is too large|Each row in p_rows must)/.test(message)
+}
+
+function liveTransport(timeoutMs: number, commandSignal: AbortSignal, progress: Progress) {
+  return {
+    append: (datasetId: string, rows: Rows) => Effect.suspend(() => {
+      let admitted = false
+      let timedOut = false
+      const attempt = new AbortController()
+      let timer: ReturnType<typeof setTimeout> | undefined
+      return Effect.tryPromise({
+        try: async signal => {
+          const abortFromEffect = () => attempt.abort(signal.reason)
+          const abortFromCommand = () => attempt.abort(commandSignal.reason)
+          try {
+            // Node 20.0 has no AbortSignal.any. This attempt owns both links
+            // and the physical fetch/body signal until its receipt is consumed.
+            if (signal.aborted) abortFromEffect()
+            else signal.addEventListener('abort', abortFromEffect, { once: true })
+            if (commandSignal.aborted) abortFromCommand()
+            else commandSignal.addEventListener('abort', abortFromCommand, { once: true })
+            const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(datasetId)}/rows`, {
+              method: 'POST', headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ rows }), signal: attempt.signal,
+            }, () => {
+              admitted = true
+              if (progress.chunk) progress.chunk.outcome = 'unknown'
+              if (timer) clearTimeout(timer)
+              timer = setTimeout(() => { timedOut = true; attempt.abort() }, timeoutMs)
+            })
+            // The single admitted-attempt deadline includes the complete body.
+            const text = await response.text()
+            let value: unknown
+            try { value = JSON.parse(text) } catch { throw new AppendFailure('Append returned an invalid acknowledgement', 'unknown') }
+            if (!response.ok) {
+              const message = value && typeof value === 'object' && 'error' in value && typeof value.error === 'string' ? value.error : ''
+              const known = response.status >= 400 && response.status < 500 && isKnownRefusal(message, response.status)
+              throw new AppendFailure(message ? `Append failed: ${message}` : 'Append failed', known ? 'rejected' : 'unknown')
+            }
+            const result = Schema.decodeUnknownResult(Acknowledgement)(value)
+            if (Result.isFailure(result) || result.success.dataset.id.toLowerCase() !== datasetId.toLowerCase() || result.success.appendedCount !== rows.length) throw new AppendFailure('Append returned an invalid acknowledgement', 'unknown')
+            return result.success
+          } finally {
+            if (timer) clearTimeout(timer)
+            signal.removeEventListener('abort', abortFromEffect)
+            commandSignal.removeEventListener('abort', abortFromCommand)
+            attempt.abort()
+          }
+        },
+        catch: cause => cause instanceof AppendFailure ? cause : new AppendFailure(
+          timedOut ? 'DATASET_TRANSFER_TIMEOUT: Dataset append exceeded its deadline' : admitted ? 'fetch failed' : cause instanceof Error ? cause.message : 'Append failed before the request was sent',
+          admitted ? 'unknown' : 'not_sent',
+        ),
+      })
+    }),
+  }
+}
+
+function recovery(progress: Progress): string {
+  if (progress.chunk?.outcome === 'unknown') return 'This chunk may already be committed. Inspect the dataset and reconcile its rows before rerunning; do not blindly repeat this write.'
+  if (progress.confirmedRows > 0) return 'Earlier acknowledged rows remain appended. Inspect the confirmed source prefix before retrying the remaining input.'
+  return 'Resolve the reported error before rerunning the command.'
+}
+
+function appendProgram(input: DatasetAppendInput, timeoutMs: number, progress: Progress, io: AppendIo, signal: AbortSignal) {
+  return Effect.gen(function*() {
+    const rows = yield* Effect.try({
+      try: () => {
+        if (extname(input.file).toLowerCase() === '.jsonl') return undefined
+        let bytes: number
+        try { bytes = statSync(input.file).size } catch (cause) {
+          const error = cause as NodeJS.ErrnoException
+          if (error.code === 'ENOENT') throw new Error(`File not found: ${input.file}. Check the path and filename, then retry.`)
+          if (error.code === 'EPERM' || error.code === 'EACCES') throw new Error(`Cannot read file: ${input.file}. Grant folder permission to your terminal app and retry.`)
+          throw new Error(`Failed to access file ${input.file}: ${error.message}`)
+        }
+        if (bytes > 50 * 1024 * 1024) throw new Error(`Input file is ${(bytes / (1024 * 1024)).toFixed(1)} MB, which exceeds the 50 MB limit. Split the file into smaller parts and append each separately.`)
+        const parsed = parseDatasetFile(input.file).rows
+        if (!Array.isArray(parsed) || parsed.length === 0) throw new Error('Dataset append file must contain at least one row')
+        return parsed
+      },
+      catch: cause => new AppendFailure(cause instanceof Error ? cause.message : 'Could not read append input', 'not_sent'),
+    })
+    const source = yield* Effect.acquireRelease(
+      Effect.sync(() => rows ? (async function*() {
+        for (let offset = 0; offset < rows.length; offset += 500) yield rows.slice(offset, offset + 500)
+      })() : streamJsonlRowChunks(input.file, { signal })),
+      iterator => Effect.promise(async () => { await iterator.return(undefined) }),
+    )
+    const transport = liveTransport(timeoutMs, signal, progress)
+    let acknowledgement: Acknowledgement | undefined
+    let index = 0
+    while (true) {
+      const next = yield* Effect.tryPromise({ try: () => source.next(), catch: cause => new AppendFailure(cause instanceof Error ? cause.message : 'Could not read append input', 'not_sent') })
+      if (next.done) break
+      index++
+      progress.chunk = { index, inputRows: next.value.length, outcome: 'not_sent' }
+      const rows = yield* Schema.decodeUnknownEffect(RowsSchema)(next.value).pipe(Effect.mapError(() => new AppendFailure('Dataset rows must be JSON objects', 'not_sent')))
+      if (!io.json) yield* Effect.sync(() => io.print(`Uploading chunk ${index} (${rows.length} rows)...`))
+      acknowledgement = yield* appendTransport.use(api => api.append(input.datasetId, rows)).pipe(Effect.provideService(appendTransport, transport))
+      progress.confirmedRows += acknowledgement.appendedCount
+      progress.confirmedChunks++
+      progress.chunk = null
+    }
+    if (!acknowledgement) return yield* Effect.fail(new AppendFailure('Dataset append file must contain at least one row', 'not_sent'))
+    return { dataset: acknowledgement.dataset, appendedCount: progress.confirmedRows }
+  }).pipe(Effect.scoped)
+}
+
+/** Owns standalone append's source, admitted writes, progress and recovery. */
+export async function appendDatasetWorkflow(resolveInput: () => Promise<DatasetAppendInput>, io: AppendIo): Promise<number> {
+  const controller = new AbortController()
+  const progress: Progress = { datasetId: null, confirmedRows: 0, confirmedChunks: 0, chunk: null }
+  let interrupted: 130 | 143 | undefined
+  const interrupt = () => { interrupted = 130; controller.abort() }
+  const terminate = () => { interrupted = 143; controller.abort() }
+  const program = Effect.gen(function*() {
+    const timeoutMs = yield* Effect.try({ try: datasetTransferTimeoutMs, catch: cause => new AppendFailure(cause instanceof Error ? cause.message : 'Invalid append configuration', 'not_sent') })
+    const input = yield* Effect.tryPromise({ try: resolveInput, catch: cause => new AppendFailure(cause instanceof Error ? cause.message : 'Could not resolve append input', 'not_sent') })
+    progress.datasetId = input.datasetId
+    // Retained interactive selection does not accept a signal. Preserve
+    // natural Node termination until we own cancellable source/transport work.
+    return yield* Effect.acquireUseRelease(
+      Effect.sync(() => { process.once('SIGINT', interrupt); process.once('SIGTERM', terminate) }),
+      () => appendProgram(input, timeoutMs, progress, io, controller.signal),
+      () => Effect.sync(() => { process.removeListener('SIGINT', interrupt); process.removeListener('SIGTERM', terminate) }),
+    )
+  })
+  const report = (message: string) => {
+    const error = sanitizeTerminalText(message)
+    const advice = recovery(progress)
+    io.print(io.json ? JSON.stringify({ error, datasetId: progress.datasetId, confirmedRows: progress.confirmedRows, confirmedChunks: progress.confirmedChunks, failedChunk: progress.chunk, recovery: advice })
+      : `${error}\n${progress.confirmedRows} rows from ${progress.confirmedChunks} chunk(s) were already appended. ${advice}`)
+  }
+  try {
+    const result = await Effect.runPromise(Effect.result(program), { signal: controller.signal })
+    if (Result.isFailure(result)) {
+      if (progress.chunk) progress.chunk.outcome = result.failure.outcome
+      report(result.failure.message)
+      return 1
+    }
+    io.print(io.json ? JSON.stringify(result.success) : `Appended ${result.success.appendedCount} rows to dataset ${sanitizeTerminalText(result.success.dataset.name)} (${sanitizeTerminalText(result.success.dataset.id)}). New row count: ${result.success.dataset.rowCount}`)
+    return 0
+  } catch {
+    report(interrupted ? 'Dataset append interrupted' : 'Dataset append failed')
+    return interrupted ?? 1
+  }
+}