@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/bin/shared-kernel/android-h5-target.js

@@ -0,0 +1,10 @@
+'use strict';
+
+const { object, text, integer } = require('./argument-schema');
+const { h5TargetContract } = require('./h5-target');
+const schema = 'aab.android-h5-target/v1';
+const pageSchema = object({ schemaVersion: { const: schema }, runtimeEpoch: text, packageName: text,
+  processId: integer(1), activity: text, windowId: text, webViewId: text, documentId: text, url: text },
+['schemaVersion', 'runtimeEpoch', 'packageName', 'processId', 'activity', 'windowId', 'webViewId', 'documentId', 'url']);
+
+module.exports = h5TargetContract({ schema, pageSchema, errorPrefix: 'android_h5' });

package/bin/shared-kernel/android-install-execution.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const { randomUUID, createHash } = require('node:crypto');
+const shell = require('./android-shell-execution');
+const { execFileBounded } = require('./execution-io');
+const { runExecution, withoutExecution, checkExecution, executionSleep } = require('./execution-scope');
+const { CommandError } = require('../command-errors');
+const { checksumOf } = require('./evidence-schema');
+
+const schema = 'aab.android-install-execution/v1';
+const root = '/data/local/tmp/ai-app-bridge-install/v1';
+const hash = value => createHash('sha256').update(value).digest('hex');
+const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+
+// This is the PackageManager CLI protocol, never an installer UI recognizer.
+// A shell process exit alone cannot settle a Binder install. Only the original
+// commit response, or proof that this worker never invoked commit, can do so.
+function installScript(identity) {
+  const directory = `${root}/${identity.installId}`;
+  return `job=${quote(directory)}\nsession=null\n` +
+    `emit() {\n` +
+    `  printf '%s' ${quote(JSON.stringify({ schemaVersion: schema, installId: identity.installId,
+      apkSha256: identity.apkSha256, packageName: identity.packageName }).slice(0, -1))}\n` +
+    `  printf ',"sessionId":%s,"phase":"%s","code":%s,"stdout":"' "$session" "$1" "$2"\n` +
+    `  base64 "$job/result.out" | tr -d '\\n'\n` +
+    `  printf '","stderr":"'; base64 "$job/result.err" | tr -d '\\n'; printf '"}'\n}\n` +
+    `: >"$job/result.out"; : >"$job/result.err"\n` +
+    `actual=$(sha256sum "$job/base.apk"); actual=\${actual%% *}\n` +
+    `if [ "$actual" != ${quote(identity.apkSha256)} ]; then emit artifact-mismatch 1; exit 0; fi\n` +
+    `pm install-create -r ${identity.allowDowngrade ? '-d ' : ''}-S ${identity.apkBytes} >"$job/result.out" 2>"$job/result.err"\ncode=$?\n` +
+    `if [ "$code" -ne 0 ]; then emit create-failed "$code"; exit 0; fi\n` +
+    `created=$(cat "$job/result.out")\nsession=$(printf '%s' "$created" | sed -n 's/^Success: created install session \\[\\([0-9][0-9]*\\)\\]$/\\1/p')\n` +
+    `case "$session" in ''|*[!0-9]*) session=null; emit create-invalid 1; exit 0;; esac\n` +
+    `printf '%s' "$session" >"$job/session.tmp" && mv "$job/session.tmp" "$job/session" || exit 1\n` +
+    `pm install-write -S ${identity.apkBytes} "$session" base.apk "$job/base.apk" >"$job/result.out" 2>"$job/result.err"\ncode=$?\n` +
+    `if [ "$code" -ne 0 ]; then emit write-failed "$code"; exit 0; fi\n` +
+    `pm install-commit "$session" >"$job/result.out" 2>"$job/result.err"\ncode=$?\n` +
+    `emit commit-returned "$code"\n`;
+}
+
+function validIdentity(identity) {
+  return identity?.kind === 'android-install' && uuid.test(identity.installId)
+    && identity.schemaVersion === shell.schema && uuid.test(identity.jobId) && uuid.test(identity.runtimeEpoch)
+    && typeof identity.actionId === 'string' && identity.actionId.length > 0 && identity.actionId.length <= 1024
+    && Number.isSafeInteger(identity.deadlineUptimeMs) && identity.deadlineUptimeMs > 0
+    && /^[a-f0-9]{64}$/.test(identity.apkSha256) && Number.isSafeInteger(identity.apkBytes) && identity.apkBytes > 0
+    && typeof identity.allowDowngrade === 'boolean' && typeof identity.packageName === 'string'
+    && identity.commandSha256 === hash(`exec ${['sh', '-c', installScript(identity)].map(quote).join(' ')}\n`);
+}
+
+function settlementProof(result, identity) {
+  if (!validIdentity(identity) || !shell.terminalReceipt(result?.shellReceipt, identity)) return null;
+  const receipt = result.shellReceipt;
+  let phase = 'not-admitted', sessionId = null, requestSucceeded = false;
+  if (receipt.dispatched) {
+    const commit = result.installResult;
+    if (receipt.exitCode !== 0 || commit?.schemaVersion !== schema || commit.installId !== identity.installId
+      || commit.apkSha256 !== identity.apkSha256 || commit.packageName !== identity.packageName || !Number.isInteger(commit.code) || commit.code < 0 || commit.code > 255
+      || typeof commit.stdout !== 'string' || typeof commit.stderr !== 'string'
+      || Buffer.from(commit.stdout, 'base64').toString('base64') !== commit.stdout
+      || Buffer.from(commit.stderr, 'base64').toString('base64') !== commit.stderr) return null;
+    phase = commit.phase; sessionId = commit.sessionId;
+    if (phase === 'commit-returned') {
+      if (!Number.isSafeInteger(sessionId) || sessionId < 1) return null;
+      const output = Buffer.from(commit.stdout, 'base64').toString('utf8').trim();
+      requestSucceeded = commit.code === 0 && output === 'Success';
+      // Pending-user-action (including Failure [null]), warnings and unknown ROM
+      // output stay unresolved. These names are final legacy PM failure codes.
+      const failed = commit.code === 1 && /^Failure \[(?:INSTALL_FAILED_|INSTALL_PARSE_FAILED_)[A-Z_]+(?:: [\s\S]*)?\]$/.test(output);
+      if (!requestSucceeded && !failed) return null;
+    } else if (!['artifact-mismatch', 'create-failed', 'create-invalid', 'write-failed'].includes(phase)
+      || commit.code === 0 || (phase === 'write-failed' ? !Number.isSafeInteger(sessionId) || sessionId < 1 : sessionId !== null)) return null;
+  }
+  return { kind: 'android-install', actionId: identity.actionId, runtimeEpoch: identity.runtimeEpoch,
+    jobId: identity.jobId, installId: identity.installId, commandSha256: identity.commandSha256,
+    deadlineUptimeMs: identity.deadlineUptimeMs, packageName: identity.packageName, apkSha256: identity.apkSha256,
+    sessionId, phase, requestSucceeded, settled: true, dispatched: phase === 'commit-returned', ambiguous: false,
+    execution: structuredClone({ shellReceipt: receipt, installResult: result.installResult }),
+    shellReceiptSha256: checksumOf(receipt),
+    responseSha256: checksumOf({ shellReceipt: receipt, installResult: result.installResult }) };
+}
+
+function createAndroidInstallPort({ adb = process.env.ADB || 'adb', serial, timeoutMs = 180000,
+  run = execFileBounded, shellPort = shell.createAndroidShellPort({ adb, serial, timeoutMs }) } = {}) {
+  const command = args => run(adb, ['-s', serial, ...args], { timeoutMs: Math.min(timeoutMs, 30000), mutation: false,
+    encoding: 'utf8', maxBuffer: 1024 * 1024, windowsHide: true });
+  const staging = script => command(['shell', 'sh', '-c', quote(script)]);
+  return {
+    async prepare(artifact, actionId, allowDowngrade = false) {
+      const installId = randomUUID(), directory = `${root}/${installId}`;
+      const identity = { kind: 'android-install', installId, packageName: artifact.packageName,
+        apkSha256: artifact.sha256, apkBytes: artifact.bytes, allowDowngrade };
+      const staged = await staging(`umask 077\nmkdir -p ${quote(root)} || exit 1\nexec 0>${quote(root + '/prepare.lock')} || exit 1\nflock -x 0 || exit 1\n` +
+        `count=0; for p in ${quote(root)}/*; do [ ! -d "$p" ] || count=$((count + 1)); done\n` +
+        `if [ "$count" -ge 64 ]; then printf '%s' '{"ok":false,"error":"install_execution_store_full"}'; exit 0; fi\n` +
+        `mkdir ${quote(directory)} || exit 1\nprintf '%s' '{"ok":true}'`);
+      let allocation;
+      try { allocation = JSON.parse(staged.stdout); }
+      catch (_) { throw new CommandError('invalid_install_staging_response', 'The phone did not confirm a private installation staging directory.'); }
+      if (allocation.ok !== true) throw new CommandError(allocation.error || 'install_staging_failed', 'The phone cannot retain another installation. Resolve existing retained jobs before retrying.');
+      try {
+        await command(['push', artifact.path, `${directory}/base.apk`]);
+        return { ...identity, ...await shellPort.prepare(['sh', '-c', installScript(identity)], actionId), target: { adb, serial } };
+      } catch (error) {
+        // No worker has been launched. The private APK is safe to remove; a
+        // prepared but undispatched shell job expires at its admission deadline.
+        try { await withoutExecution(() => staging(`rm -rf ${quote(directory)}`)); }
+        catch (cleanup) { error.cleanupError = cleanup.code || 'install_staging_cleanup_failed'; }
+        throw error;
+      }
+    },
+    start: identity => shellPort.start(identity),
+    async read(identity, cancel = false) {
+      if (!validIdentity(identity)) throw new CommandError('invalid_install_execution_identity', 'The original installation identity is invalid.');
+      const shellReceipt = await (cancel ? shellPort.cancel(identity) : shellPort.query(identity));
+      const result = { shellReceipt, installResult: null };
+      if (shell.terminalReceipt(shellReceipt, identity) && shellReceipt.dispatched && shellReceipt.exitCode === 0) {
+        const output = await shellPort.output(identity);
+        try { result.installResult = JSON.parse(output.stdout); }
+        catch (_) { throw new CommandError('invalid_install_execution_response', 'The original installer response is missing or incomplete.'); }
+      }
+      return result;
+    },
+    async acknowledge(identity, result) {
+      const proof = settlementProof(result, identity);
+      if (!proof) throw new CommandError('invalid_install_execution_receipt', 'Installation cleanup requires the original completion receipt.');
+      if (proof.phase === 'write-failed') {
+        const abandoned = await command(['shell', 'pm', 'install-abandon', String(proof.sessionId)]);
+        if (abandoned.stdout.trim() !== 'Success') throw new CommandError('install_session_cleanup_failed', 'The uncommitted install session could not be abandoned.');
+      }
+      await staging(`rm -rf ${quote(`${root}/${identity.installId}`)}`);
+      const ack = await shellPort.acknowledge(identity, result.shellReceipt);
+      if (ack.ok !== true || ack.acknowledged !== true) throw new CommandError(ack.error || 'install_receipt_acknowledgement_failed', 'The installation shell receipt could not be acknowledged.');
+      return { ok: true, acknowledged: true };
+    },
+  };
+}
+
+async function prepareInstallJob(args, artifact, actionId, port = createAndroidInstallPort(args)) {
+  const timeoutMs = args.timeoutMs ?? 180000, startedAtMs = Date.now(), controller = new AbortController();
+  const identity = await runExecution({ timeoutMs }, () => port.prepare(artifact, actionId, args.allowDowngrade === true));
+  let started = false, cancelled = false, resolveDone;
+  const done = new Promise(resolve => { resolveDone = resolve; });
+  async function execute() {
+    let value, failure;
+    try {
+      value = await withoutExecution(() => runExecution({ deadlineMs: startedAtMs + timeoutMs, signal: controller.signal }, async () => {
+        checkExecution();
+        const submitted = await port.start(identity);
+        if (submitted.ok !== true || submitted.submitted !== true) throw new CommandError(submitted.error || 'install_submission_failed', 'The original install worker was not admitted.');
+        for (;;) {
+          checkExecution(); const reply = await port.read(identity);
+          if (reply.shellReceipt?.settled === true) return reply;
+          if (reply.shellReceipt?.ok !== true) throw new CommandError(reply.shellReceipt?.error || 'install_query_failed', 'The original installation could not be queried.');
+          await executionSleep(100);
+        }
+      }));
+    } catch (error) {
+      failure = error.code || 'install_response_lost';
+      try { value = await withoutExecution(() => port.read(identity, true)); }
+      catch (recovery) { failure = recovery.code || 'install_completion_unavailable'; }
+    }
+    const proof = settlementProof(value, identity);
+    resolveDone({ identity, ...value, executionReceipt: proof, settled: Boolean(proof), dispatched: proof?.dispatched ?? null,
+      ambiguous: !proof, requestSucceeded: proof?.requestSucceeded === true, cancelled,
+      timedOut: Date.now() >= startedAtMs + timeoutMs, error: proof ? (failure ?? null) : (failure || 'install_completion_unavailable'),
+      startedAtMs, completedAtMs: Date.now() });
+  }
+  const start = () => { if (!started) { started = true; void execute(); } return done; };
+  return { identity, done, start, cancel() { cancelled = true; controller.abort({ code: 'installation_cancelled' }); return start(); },
+    status: () => ({ identity, startedAtMs, cancelled }),
+    acknowledge: result => port.acknowledge(identity, { shellReceipt: result.shellReceipt, installResult: result.installResult }) };
+}
+
+module.exports = { schema, installScript, validIdentity, settlementProof, createAndroidInstallPort, prepareInstallJob };

package/bin/shared-kernel/android-sdk-endpoint.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const { CommandError } = require('../command-errors');
+
+const schema = 'ai-app-bridge.android-endpoint.v1';
+const endpointPath = 'files/ai_app_bridge_endpoint.json';
+const epochPattern = /^[0-9]{13}-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function parseAndroidSdkEndpoint(text, packageName) {
+  const invalid = reason => new CommandError('bridge_endpoint_invalid', `Invalid SDK endpoint for ${packageName}: ${reason}.`, { field: 'endpoint' });
+  let endpoint;
+  try { endpoint = JSON.parse(text); }
+  catch (_) { throw invalid('expected JSON'); }
+  if (!endpoint || typeof endpoint !== 'object' || Array.isArray(endpoint)
+    || endpoint.schema !== schema) throw invalid(`expected schema ${schema}`);
+  if (endpoint.packageName !== packageName) throw new CommandError('bridge_package_mismatch',
+    `SDK endpoint package mismatch: expected ${packageName}, got ${endpoint.packageName}.`, { field: 'packageName' });
+  if (endpoint.transport !== 'localabstract') throw invalid('transport must be localabstract');
+  if (typeof endpoint.runtimeEpoch !== 'string' || !epochPattern.test(endpoint.runtimeEpoch)
+    || endpoint.socketName !== `aab-sdk-${endpoint.runtimeEpoch}`) throw invalid('socket name must match runtimeEpoch');
+  if (typeof endpoint.version !== 'string' || !endpoint.version
+    || !Number.isSafeInteger(endpoint.updatedAtMs) || endpoint.updatedAtMs <= 0) throw invalid('missing version or update time');
+  if (endpoint.ok === false) throw new CommandError('bridge_not_ready',
+    `SDK endpoint for ${packageName} is not ready: ${endpoint.error}.`, { field: 'endpoint' });
+  if (endpoint.ok !== true) throw invalid('ok must be a boolean');
+  return endpoint;
+}
+
+async function discoverAndroidSdkEndpoint(ctx, adb) {
+  if (!ctx.packageName) throw new CommandError('target_required', 'SDK commands require packageName.', { field: 'packageName' });
+  let text;
+  try { text = (await adb(ctx, ['shell', 'run-as', ctx.packageName, 'cat', endpointPath])).stdout; }
+  catch (error) {
+    if (error instanceof CommandError) throw error;
+    throw new CommandError('bridge_endpoint_discovery_failed',
+      `Cannot read ${endpointPath} for ${ctx.packageName}. Install and launch a debuggable build with the current Android SDK.`,
+      { field: 'packageName', details: { cause: String(error.message).split(/\r?\n/)[0] } });
+  }
+  return parseAndroidSdkEndpoint(text, ctx.packageName);
+}
+
+module.exports = { schema, endpointPath, parseAndroidSdkEndpoint, discoverAndroidSdkEndpoint };

package/bin/shared-kernel/android-shell-execution.js

@@ -0,0 +1,195 @@
+'use strict';
+
+const { randomUUID, createHash } = require('node:crypto');
+const { execFileBounded } = require('./execution-io');
+const { runExecution, checkExecution, currentExecution, withoutExecution, executionSleep, markExecutionDispatched } = require('./execution-scope');
+const { runDeviceEffect, isDeviceSettlementDurable } = require('./device-mutation-lease');
+const { CommandError } = require('../command-errors');
+
+const schema = 'aab.android-shell-execution/v1';
+const rootDirectory = '/data/local/tmp/ai-app-bridge-shell/v1';
+const maxRetainedJobs = 512;
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const digest = value => createHash('sha256').update(value).digest('hex');
+const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+const uptimeScript = 'read up ignored < /proc/uptime\nuptime_ms=$(( ${up%.*} * 1000 + 10#${up#*.} * 10 ))\n';
+
+// Each immutable job directory belongs to one command and one Android boot.
+// The detached worker publishes a terminal receipt only after the command exits.
+// Cancellation can win admission. Once admitted, the original command drains;
+// killing a client or its Binder caller is not remote completion evidence.
+function createAndroidShellPort({ adb, serial, timeoutMs = 15000, run = execFileBounded } = {}) {
+  if (typeof serial !== 'string' || !serial) throw new CommandError('serial_required', 'Android shell execution requires serial.');
+  const shell = (script, budgetMs=timeoutMs) => run(adb, ['-s', serial, 'shell', 'sh', '-c', quote(script)], {
+    timeoutMs:budgetMs, mutation: false, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, windowsHide: true,
+  }).then(r => r.stdout.trim());
+  const request = async (script,budgetMs) => {
+    let text;
+    try { text = await shell(script,budgetMs); }
+    catch (error) {
+      throw new CommandError(typeof error.code === 'string' && /^[a-z][a-z0-9_]*$/.test(error.code) ? error.code : 'shell_transport_failed',
+        'Android shell transport failed.', { dispatched: error.dispatched ?? null, ambiguous: error.ambiguous ?? true,
+          details: { cause: error.code ?? null, stderr: String(error.stderr ?? '').trim().slice(0, 1024) } });
+    }
+    try { return JSON.parse(text); }
+    catch (_) { throw new CommandError('invalid_shell_execution_response', 'The device did not return a valid shell execution response.', { dispatched: null, ambiguous: true }); }
+  };
+  const identityFields = identity => {
+    if (!uuid.test(identity.jobId) || !uuid.test(identity.runtimeEpoch) || typeof identity.actionId !== 'string'
+      || !identity.actionId || identity.actionId.length>1024 || !/^[a-f0-9]{64}$/.test(identity.commandSha256)
+      || !Number.isSafeInteger(identity.deadlineUptimeMs) || identity.deadlineUptimeMs<1) throw new CommandError('invalid_shell_execution_identity', 'An original shell action identity is required.');
+    return { schemaVersion: schema, actionId: identity.actionId, jobId: identity.jobId,
+      runtimeEpoch: identity.runtimeEpoch, commandSha256: identity.commandSha256, deadlineUptimeMs:identity.deadlineUptimeMs };
+  };
+  const checkedDirectory = identity => {
+    const fields = identityFields(identity), directory = `${rootDirectory}/${fields.jobId}`;
+    return { fields, directory, guard: `job=${quote(directory)}\nexpected=${quote(JSON.stringify(fields))}\n` +
+      `if [ "$(cat /proc/sys/kernel/random/boot_id)" != ${quote(fields.runtimeEpoch)} ]; then printf '%s' '{"ok":false,"error":"shell_runtime_changed"}'; exit 0; fi\n` +
+      `if [ ! -f "$job/identity.json" ] || [ "$(cat "$job/identity.json")" != "$expected" ]; then printf '%s' '{"ok":false,"error":"shell_execution_not_found"}'; exit 0; fi\n` };
+  };
+  return {
+    async prepare(argv, actionId = randomUUID()) {
+      if (!Array.isArray(argv) || !argv.length || !argv[0] || argv.some(v => typeof v !== 'string' || v.includes('\0'))) {
+        throw new CommandError('invalid_shell_arguments', 'Shell arguments must be nonempty string argv without NUL.');
+      }
+      const deadlineMs=Math.min(currentExecution()?.deadlineMs??Infinity,Date.now()+timeoutMs);
+      const probe=await request(`command -v setsid >/dev/null && command -v nohup >/dev/null || exit 1\n${uptimeScript}`+
+        `printf '{"runtimeEpoch":"%s","uptimeMs":%s}' "$(cat /proc/sys/kernel/random/boot_id)" "$uptime_ms"`);
+      if (!uuid.test(probe.runtimeEpoch)||!Number.isSafeInteger(probe.uptimeMs)||probe.uptimeMs<0) throw new CommandError('shell_runtime_unavailable', 'Android boot identity and monotonic uptime are unavailable.');
+      const remaining=Math.floor(deadlineMs-Date.now());
+      if(remaining<1)throw new CommandError('deadline_exceeded','The execution budget expired before shell preparation.');
+      const command = `exec ${argv.map(quote).join(' ')}\n`;
+      if (Buffer.byteLength(command) > 65536) throw new CommandError('shell_arguments_too_large', 'The serialized shell command exceeds 64 KiB.');
+      const identity={schemaVersion:schema,actionId,jobId:randomUUID(),runtimeEpoch:probe.runtimeEpoch,commandSha256:digest(command),deadlineUptimeMs:probe.uptimeMs+remaining};
+      const fields = identityFields(identity), directory = `${rootDirectory}/${fields.jobId}`;
+      const prefix = JSON.stringify(fields).slice(0,-1);
+      const completedPrefix = `${prefix},"ok":true,"settled":true,"dispatched":true,"ambiguous":false,"exitCode":`;
+      const expired = JSON.stringify({ ...fields, ok:false, error:'shell_action_timeout', settled:true, dispatched:false, ambiguous:false, exitCode:null });
+      const worker = `job=${quote(directory)}\n` +
+        `if ! mkdir "$job/admission" 2>/dev/null; then exit 0; fi\n` +
+        `if [ "$(cat /proc/sys/kernel/random/boot_id)" != ${quote(fields.runtimeEpoch)} ]; then exit 1; fi\n` +
+        `actual=$(sha256sum "$job/command.sh"); actual=\${actual%% *}\n` +
+        `if [ "$actual" != ${quote(fields.commandSha256)} ]; then exit 1; fi\n` +
+        uptimeScript +
+        `if [ "$uptime_ms" -ge ${fields.deadlineUptimeMs} ]; then printf '%s' ${quote(expired)} >"$job/receipt.tmp" && mv "$job/receipt.tmp" "$job/receipt.json"; exit 0; fi\n` +
+        `ulimit -f 128 || exit 1\n` +
+        `sh "$job/command.sh" >"$job/stdout" 2>"$job/stderr"\ncode=$?\n` +
+        `printf '%s%s%s' ${quote(completedPrefix)} "$code" '}' >"$job/receipt.tmp" && mv "$job/receipt.tmp" "$job/receipt.json"\n`;
+      const prepared=await request(`umask 077\nmkdir -p ${quote(rootDirectory)} || exit 1\n` +
+        // Android mksh closes descriptors above 2 when launching flock. This
+        // noninteractive staging shell retains its lock through inherited stdin.
+        `exec 0>${quote(rootDirectory + '/prepare.lock')} || exit 1\nflock -x 0 || exit 1\n` +
+        `count=0\nfor candidate in ${quote(rootDirectory)}/*; do\n` +
+        `  [ -d "$candidate" ] || continue\n` +
+        `  if [ -f "$candidate/acknowledged" ]; then rm -rf "$candidate" || exit 1; else count=$((count + 1)); fi\ndone\n` +
+        `if [ "$count" -ge ${maxRetainedJobs} ]; then printf '%s' '{"ok":false,"error":"shell_execution_store_full"}'; exit 0; fi\njob=${quote(directory)}\n` +
+        `if ! mkdir "$job" 2>/dev/null; then printf '%s' '{"ok":false,"error":"shell_action_id_reused"}'; exit 0; fi\n` +
+        `printf '%s' ${quote(JSON.stringify(fields))} >"$job/identity.tmp" && mv "$job/identity.tmp" "$job/identity.json" || exit 1\n` +
+        `printf '%s' ${quote(command)} >"$job/command.sh" || exit 1\n` +
+        `printf '%s' ${quote(worker)} >"$job/worker.sh" || exit 1\n` +
+        `printf '%s' '{"ok":true,"prepared":true}'`);
+      if(prepared.ok!==true||prepared.prepared!==true)throw new CommandError(prepared.error||'shell_preparation_failed','The Android shell job could not be prepared.');
+      return identity;
+    },
+    async start(identity) {
+      const {guard}=checkedDirectory(identity);
+      return request(guard+
+        `if ! mkdir "$job/launched" 2>/dev/null; then printf '%s' '{"ok":false,"error":"shell_action_id_reused"}'; exit 0; fi\n`+
+        `setsid nohup sh "$job/worker.sh" </dev/null >"$job/worker.log" 2>&1 &\n` +
+        `printf '%s' '{"ok":true,"submitted":true}'`);
+    },
+    async query(identity) {
+      const {guard}=checkedDirectory(identity);
+      return request(guard + `if [ -f "$job/receipt.json" ]; then cat "$job/receipt.json"; else printf '%s' '{"ok":true,"settled":false}'; fi`);
+    },
+    async cancel(identity) {
+      const {guard,fields}=checkedDirectory(identity);
+      const cancelled=JSON.stringify({...fields,ok:false,error:'shell_action_cancelled',settled:true,dispatched:false,ambiguous:false,exitCode:null});
+      return request(guard + `if mkdir "$job/admission" 2>/dev/null; then printf '%s' ${quote(cancelled)} >"$job/cancel.tmp" && mv "$job/cancel.tmp" "$job/receipt.json"; fi\n` +
+        `if [ -f "$job/receipt.json" ]; then cat "$job/receipt.json"; else printf '%s' '{"ok":true,"settled":false}'; fi`,3000);
+    },
+    async output(identity) {
+      const {guard}=checkedDirectory(identity);
+      const result = await request(guard + `if [ ! -f "$job/receipt.json" ]; then printf '%s' '{"ok":false,"error":"shell_action_not_settled"}'; exit 0; fi\n` +
+        `printf '{"ok":true,"stdout":"'; if [ -f "$job/stdout" ]; then base64 "$job/stdout" | tr -d '\\n'; fi\n` +
+        `printf '","stderr":"'; if [ -f "$job/stderr" ]; then base64 "$job/stderr" | tr -d '\\n'; fi; printf '"}'`);
+      if (!result.ok) throw new CommandError(result.error, 'The original shell command output is unavailable.', { dispatched:null, ambiguous:true });
+      return { stdout:Buffer.from(result.stdout,'base64').toString('utf8'), stderr:Buffer.from(result.stderr,'base64').toString('utf8') };
+    },
+    async acknowledge(identity, receipt) {
+      if (!terminalReceipt(receipt, identity)) throw new CommandError('invalid_shell_execution_receipt', 'Only the original terminal receipt may be acknowledged.');
+      const { guard } = checkedDirectory(identity);
+      const { executionReceipt, ...wireReceipt } = receipt;
+      const expected = JSON.stringify(wireReceipt);
+      return request(guard + `if [ "$(cat "$job/receipt.json")" != ${quote(expected)} ]; then printf '%s' '{"ok":false,"error":"shell_receipt_changed"}'; exit 0; fi\n` +
+        `printf '%s' ${quote(digest(expected))} >"$job/acknowledged.tmp" && mv "$job/acknowledged.tmp" "$job/acknowledged" || exit 1\n` +
+        `printf '%s' '{"ok":true,"acknowledged":true}'`, 1000);
+    },
+  };
+}
+
+function terminalReceipt(result, identity) {
+  return result?.schemaVersion===schema && result.actionId===identity.actionId && result.jobId===identity.jobId
+    && result.runtimeEpoch===identity.runtimeEpoch && result.commandSha256===identity.commandSha256
+    && result.deadlineUptimeMs===identity.deadlineUptimeMs
+    && result.settled===true && typeof result.dispatched==='boolean' && result.ambiguous===false
+    && (result.dispatched ? result.ok===true && Number.isInteger(result.exitCode) && result.exitCode>=0 && result.exitCode<=255
+      : result.ok===false && ['shell_action_cancelled','shell_action_timeout'].includes(result.error) && result.exitCode===null);
+}
+function settlementProof(result, identity) {
+  if (!terminalReceipt(result, identity)) return null;
+  const { executionReceipt, ...wireReceipt } = result;
+  return { kind:'android-shell', actionId:identity.actionId, runtimeEpoch:identity.runtimeEpoch, jobId:identity.jobId,
+    commandSha256:identity.commandSha256, deadlineUptimeMs:identity.deadlineUptimeMs, settled:true, dispatched:result.dispatched, ambiguous:false,
+    exitCode:result.exitCode, error:result.error??null, responseSha256:digest(JSON.stringify(wireReceipt)) };
+}
+
+async function executeAndroidShell({ adb, serial, argv, actionId, timeoutMs=15000, port=createAndroidShellPort({adb,serial,timeoutMs}) }) {
+  return runExecution({timeoutMs,mutation:true},()=>executeWithinScope({adb,serial,argv,actionId,port}));
+}
+async function executeWithinScope({adb,serial,argv,actionId,port}) {
+  const prepared = await port.prepare(argv,actionId);
+  const identity=prepared;
+  let failure;
+  const result = await runDeviceEffect({kind:'android-shell',...identity,target:{adb,serial}},async()=>{
+    try {
+      checkExecution(); markExecutionDispatched();
+      const submitted=await port.start(prepared);
+      if (!submitted.ok) throw new Error(submitted.error);
+      while(true){
+        checkExecution();const receipt=await port.query(identity);
+        if(terminalReceipt(receipt,identity)) return { ...receipt,executionReceipt:settlementProof(receipt,identity) };
+        if(receipt?.ok!==true||receipt.settled!==false) throw new Error(receipt?.error||'invalid_shell_execution_receipt');
+        await executionSleep(60);
+      }
+    } catch(error){failure=error.code||'shell_action_response_lost';}
+    let receipt;
+    try{receipt=await withoutExecution(()=>port.cancel(identity));}catch(_){/* Missing cancellation remains unresolved. */}
+    if(terminalReceipt(receipt,identity))return {...receipt,executionReceipt:settlementProof(receipt,identity)};
+    return {ok:false,error:failure, ...identity,settled:false,dispatched:null,ambiguous:true,executionReceipt:null};
+  },value=>settlementProof(value,identity));
+  if(!result.executionReceipt)throw Object.assign(new CommandError(result.error,'The original Android shell command has not confirmed completion.',{dispatched:null,ambiguous:true}),{settled:false,executionReceipt:null});
+  let output;
+  try { output=await withoutExecution(()=>port.output(identity)); }
+  catch (error) {
+    throw new CommandError('shell_output_unavailable', 'The command completed, but its output could not be read.', {
+      dispatched: result.dispatched, ambiguous: false, settled: true, executionReceipt: result.executionReceipt,
+      exitCode: result.exitCode, details: { cause: error.code || 'shell_output_read_failed' },
+    });
+  }
+  // Ownership has already fsynced this exact proof. A failed acknowledgement
+  // retains the phone copy; it cannot undo the confirmed execution outcome.
+  let cleanupError;
+  if (isDeviceSettlementDurable(result.executionReceipt)) {
+    try {
+      const ack = await withoutExecution(() => port.acknowledge(identity, result));
+      if (ack.ok !== true || ack.acknowledged !== true) cleanupError = ack.error || 'shell_receipt_acknowledgement_failed';
+    } catch (error) { cleanupError = error.code || 'shell_receipt_acknowledgement_failed'; }
+  }
+  if (cleanupError) output.cleanupError = cleanupError;
+  if(failure||result.exitCode!==0)throw Object.assign(new CommandError(failure||result.error||'adb_command_failed',output.stderr||'The Android shell command did not complete successfully.',{dispatched:result.dispatched,ambiguous:false}),
+    {...output,settled:true,executionReceipt:result.executionReceipt,exitCode:result.exitCode});
+  return {...output,settled:true,dispatched:result.dispatched,ambiguous:false,executionReceipt:result.executionReceipt};
+}
+
+module.exports={schema,createAndroidShellPort,executeAndroidShell,terminalReceipt,settlementProof};

package/bin/shared-kernel/argument-schema.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const { CommandError } = require('../command-errors');
+
+const fieldAt = (parent, name) => parent ? `${parent}.${name}` : name;
+const invalid = (field, message) => new CommandError('invalid_argument', message, { field: field || 'arguments' });
+
+// Validate the JSON Schema subset emitted by the command registry. Defaults
+// describe the contract; validation never invents a value or converts its type.
+function validateValue(value, schema, field = '') {
+  const label = field || 'arguments';
+  if (schema === true) return validateJson(value, field);
+  if (schema === false) throw invalid(field, `${label} is not accepted.`);
+  if (Object.hasOwn(schema, 'const') && value !== schema.const) throw invalid(field, `${label} must be ${JSON.stringify(schema.const)}.`);
+  if (schema.enum && !schema.enum.includes(value)) throw invalid(field, `${label} must be one of: ${schema.enum.join(', ')}.`);
+  const type = schema.type;
+  const matches = type === undefined || (type === 'array' ? Array.isArray(value)
+    : type === 'null' ? value === null
+    : type === 'object' ? value !== null && typeof value === 'object' && !Array.isArray(value)
+    : type === 'integer' ? Number.isSafeInteger(value)
+    : type === 'number' ? typeof value === 'number' && Number.isFinite(value)
+    : typeof value === type);
+  if (!matches) throw invalid(field, `${label} must be ${type}; no implicit type conversion is performed.`);
+  if (schema.minLength !== undefined && value.length < schema.minLength) throw invalid(field, `${label} must not be empty.`);
+  if (schema.maxLength !== undefined && value.length > schema.maxLength) throw invalid(field, `${label} must contain at most ${schema.maxLength} characters.`);
+  if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) throw invalid(field, `${label} must match ${schema.pattern}.`);
+  if (schema.minimum !== undefined && value < schema.minimum) throw invalid(field, `${label} must be >= ${schema.minimum}.`);
+  if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) throw invalid(field, `${label} must be > ${schema.exclusiveMinimum}.`);
+  if (schema.maximum !== undefined && value > schema.maximum) throw invalid(field, `${label} must be <= ${schema.maximum}.`);
+  if (type === 'array') {
+    if (schema.minItems !== undefined && value.length < schema.minItems) throw invalid(field, `${label} requires at least ${schema.minItems} item(s).`);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) throw invalid(field, `${label} accepts at most ${schema.maxItems} item(s).`);
+    value.forEach((item, index) => validateValue(item, schema.items ?? {}, `${label}[${index}]`));
+    if (schema.uniqueItems && new Set(value.map(item => JSON.stringify(item))).size !== value.length) throw invalid(field, `${label} must not contain duplicate items.`);
+  }
+  if (type === 'object' || schema.properties || schema.required || schema.additionalProperties !== undefined) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) throw invalid(field, `${label} must be an object.`);
+    if (![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw invalid(field, `${label} must be a JSON object.`);
+    const properties = schema.properties || {};
+    for (const name of schema.required || []) {
+      if (!Object.hasOwn(value, name)) throw new CommandError('missing_argument', `${fieldAt(field, name)} is required.`, { field: fieldAt(field, name) });
+    }
+    for (const [name, rule] of Object.entries(properties)) {
+      if (Object.hasOwn(value, name) && (Object.hasOwn(rule, 'const') || rule.enum)) validateValue(value[name], rule, fieldAt(field, name));
+    }
+    // Validate the selected operation before its aggregate discovery properties.
+    // Otherwise a wrong field can fail a different operation's nested union.
+    if (schema.anyOf) validateUnion(value, schema.anyOf, field, false);
+    if (schema.oneOf) validateUnion(value, schema.oneOf, field, true);
+    for (const [name, item] of Object.entries(value)) {
+      const child = fieldAt(field, name);
+      if (Object.hasOwn(properties, name)) validateValue(item, properties[name], child);
+      else if (schema.additionalProperties === false) throw new CommandError('unsupported_argument', `${child} is not accepted by this contract.`, { field: child });
+      else if (schema.additionalProperties && typeof schema.additionalProperties === 'object') validateValue(item, schema.additionalProperties, child);
+      else if (type === 'object') validateJson(item, child);
+    }
+  }
+  for (const part of schema.allOf || []) validateValue(value, part, field);
+  if (!(type === 'object' || schema.properties || schema.required || schema.additionalProperties !== undefined)) {
+    if (schema.anyOf) validateUnion(value, schema.anyOf, field, false);
+    if (schema.oneOf) validateUnion(value, schema.oneOf, field, true);
+  }
+  if (schema.not && accepts(value, schema.not, field)) throw invalid(field, `${label} combines mutually exclusive fields.`);
+  if (schema.if) {
+    const branch = accepts(value, schema.if, field) ? schema.then : schema.else;
+    if (branch) validateValue(value, branch, field);
+  }
+  if (Object.keys(schema).every(key => ['description', 'default'].includes(key))) validateJson(value, field);
+}
+
+function accepts(value, schema, field) {
+  try { validateValue(value, schema, field); return true; }
+  catch (error) { if (!(error instanceof CommandError)) throw error; return false; }
+}
+
+function validateUnion(value, branches, field, exactlyOne) {
+  const failures = [];
+  let matched = 0;
+  for (const branch of branches) {
+    try { validateValue(value, branch, field); matched++; }
+    catch (error) { if (!(error instanceof CommandError)) throw error; failures.push({ branch, error }); }
+  }
+  if (matched && (!exactlyOne || matched === 1)) return;
+  if (!matched) {
+    // A tagged branch gives a useful precise error instead of a generic union
+    // failure, e.g. decision.action.durationMs for an observed long press.
+    const tagged = failures.filter(({ branch }) => {
+      const tags = Object.entries(branch.properties || {}).filter(([, rule]) => Object.hasOwn(rule, 'const'));
+      return tags.some(([key, rule]) => value?.[key] === rule.const)
+        && tags.every(([key, rule]) => Object.hasOwn(value || {}, key) ? value[key] === rule.const : !branch.required?.includes(key));
+    });
+    if (tagged.length === 1) throw tagged[0].error;
+    const candidates = tagged.length ? tagged : failures;
+    if (candidates.every(({ error }) => error.code === candidates[0].error.code && error.field === candidates[0].error.field && error.message === candidates[0].error.message)) throw candidates[0].error;
+    if (branches.length === 1) throw failures[0].error;
+  }
+  throw new CommandError('invalid_argument', `${field || 'arguments'} must match ${exactlyOne ? 'exactly one' : 'one'} of the documented variants.`,
+    { field: field || 'arguments', details: { variants: failures.map(({ error }) => ({ field: error.field, error: error.code, message: error.message })) } });
+}
+
+function validateJson(value, field = '', ancestors = new Set(), depth = 0) {
+  if (depth > 64) throw invalid(field, 'JSON nesting must not exceed 64 levels.');
+  if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value)) return;
+  if (typeof value !== 'object') throw invalid(field, `${field || 'value'} must be a JSON value.`);
+  if (ancestors.has(value)) throw invalid(field, `${field || 'value'} must not contain a cycle.`);
+  if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw invalid(field, `${field || 'value'} must be a JSON object.`);
+  ancestors.add(value);
+  for (const [key, item] of Object.entries(value)) validateJson(item, Array.isArray(value) ? `${field}[${key}]` : fieldAt(field, key), ancestors, depth + 1);
+  ancestors.delete(value);
+}
+
+const object = (properties, required = []) => ({ type: 'object', additionalProperties: false, properties, required });
+const integer = (minimum, maximum = Number.MAX_SAFE_INTEGER) => ({ type: 'integer', minimum, maximum });
+const text = { type: 'string', minLength: 1 };
+const milliseconds = integer(1, 2147483647);
+
+module.exports = { validateValue, validateJson, object, integer, text, milliseconds };

package/bin/shared-kernel/canonical-path.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Resolve existing ancestors too, so a not-yet-created store has the same
+// identity before and after mkdir, including macOS /var and /private/var.
+function canonicalPath(input) {
+  const absolute = path.resolve(input);
+  try { return fs.realpathSync(absolute); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return path.join(canonicalPath(path.dirname(absolute)), path.basename(absolute));
+  }
+}
+
+module.exports = { canonicalPath };

package/bin/shared-kernel/device-acknowledgements.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const { isDeepStrictEqual } = require('node:util');
+const { CommandError } = require('../command-errors');
+const uia = require('./uia-protocol');
+const path = require('node:path');
+
+const capacity = 8;
+
+// These are cleanup obligations, never an alternative completion authority.
+// Keep both original request and receipt bytes after the effect marker clears.
+function completion(pending, proof) {
+  const response = { schemaVersion: proof?.schemaVersion, bootId: proof?.bootId, runtimeEpoch: proof?.runtimeEpoch,
+    actionId: proof?.actionId, requestSha256: proof?.requestSha256, settled: true,
+    receiptJson: proof?.receiptJson, receiptSha256: proof?.responseSha256 };
+  const expected = uia.settlementProof(response, pending);
+  if (!expected || !isDeepStrictEqual(expected, proof))
+    throw new CommandError('device_acknowledgement_invalid', 'Acknowledgement requires the exact original UIA request and durable completion receipt.');
+  return response;
+}
+
+function entry(pending, proof) {
+  if (pending.kind !== 'uia-node' || typeof proof?.receiptJson !== 'string') return null;
+  completion(pending, proof);
+  return structuredClone({ pending, proof, historyTarget: require('./host-fact-store').hostFactStoreTarget() });
+}
+
+function valid(entry, serial) {
+  if (!entry || typeof entry !== 'object' || Object.keys(entry).length !== 3 || !entry.pending || !entry.proof
+    || typeof entry.pending.id !== 'string' || !entry.pending.id || entry.pending.target?.serial !== serial
+    || !entry.historyTarget || typeof entry.historyTarget.directory !== 'string' || !path.isAbsolute(entry.historyTarget.directory)
+    || !['auto', '64mb', '256mb', '512mb', '1gb'].includes(entry.historyTarget.profile)) return false;
+  try { completion(entry.pending, entry.proof); return true; } catch { return false; }
+}
+
+function checkCapacity(state, descriptor) {
+  if (descriptor.kind === 'uia-node' && state.pendingAcknowledgements.length >= capacity)
+    throw new CommandError('device_acknowledgements_full', 'UIA has 8 pending receipt acknowledgements. Run device-ownership reconcile before another UIA action.',
+      { dispatched: false, ambiguous: false });
+}
+
+function append(state, pending, proof) {
+  const next = entry(pending, proof);
+  if (!next) return;
+  checkCapacity(state, pending);
+  if (state.pendingAcknowledgements.some(item => item.pending.id === pending.id))
+    throw new CommandError('device_acknowledgement_invalid', 'This original action already has a pending acknowledgement.');
+  state.pendingAcknowledgements.push(next);
+}
+
+const accepted = value => value?.ok === true && ['acknowledged', 'not_retained'].includes(value.disposition);
+
+module.exports = { capacity, completion, entry, valid, checkCapacity, append, accepted };