agent-repl 0.1.0

package/dist/shared/REPL_SESSION_RECORD_PROTOCOL.md

@@ -0,0 +1,105 @@
+# Shared REPL session record protocol v1
+
+This protocol lets independent `pi-repl` and `pi-studio` installations exchange a clean code/output record while using the same tmux REPL session. Neither package imports or requires the other. If the protocol is unavailable or invalid, each package keeps its existing standalone behavior and the raw tmux pane/history remains usable.
+
+## Discovery and identity
+
+Compatible clients inspect two tmux session options:
+
+- `@pi_repl_record_id`: 32 lowercase hexadecimal characters
+- `@pi_repl_record_version`: `1`
+
+A client creating metadata uses tmux `set-option -o`, so concurrent first writers cannot replace an ID already chosen by another client. The option contains an opaque ID, never a filesystem path.
+
+The record is bound to:
+
+- the tmux session name
+- `#{session_id}`
+- `#{session_created}`
+
+A client refuses a record whose stored identity does not match the live tmux session. Runtime metadata continues to use `@pi_repl_runtime`.
+
+## Storage and permissions
+
+The opaque ID maps to:
+
+```text
+<os temporary directory>/pi-repl-session-records-<uid>/<record-id>.json
+```
+
+The root is a real, current-user-owned mode-`0700` directory. Record files are single-link regular, current-user-owned mode-`0600` files. Symlinked roots, records, lock paths, and hard-linked records are refused. Writes use a same-directory exclusive temporary file, file fsync, atomic rename, and best-effort directory fsync.
+
+The record is a bounded JSON snapshot:
+
+```json
+{
+  "protocol": "pi-repl-session-record",
+  "version": 1,
+  "recordId": "…",
+  "session": {
+    "sessionName": "pi-repl-python",
+    "tmuxSessionId": "$1",
+    "tmuxSessionCreatedAt": 1700000000,
+    "runtime": "ipython"
+  },
+  "revision": 4,
+  "createdAt": 1700000000000,
+  "updatedAt": 1700000005000,
+  "clearedAt": null,
+  "droppedEntries": 0,
+  "entries": []
+}
+```
+
+Each entry has a stable `id`, optional `requestId`, timestamps, session/runtime identity, `origin` (`pi-repl` or `pi-studio`), a presentation `label`, `mode` (`raw`, `literate`, or `agent`), prose, code, cleaned output, status, and skipped/truncation metadata.
+
+## Concurrency and bounds
+
+Record updates take a short cross-process directory lock, read the latest snapshot, upsert by stable entry ID, and replace the snapshot atomically. A stale lock can be recovered. The implementation retains at most 300 entries, bounds individual prose/code/output fields, and caps the serialized record at 16 MiB by dropping the oldest entries first.
+
+Attribution-sensitive sends also take a separate cross-client send lease. A compatible client holds it from the pre-send pane capture through the completion/output capture. The lease has an owner token, heartbeat, bounded wait, and stale recovery. If a caller times out or aborts after submission, the live client continues heartbeating the lease until the runtime completion signal appears or that exact tmux session lifetime ends; a caller timeout does not imply that submitted code stopped. This prevents `pi-repl` and `pi-studio` from concurrently claiming each other's output; it cannot prevent a person typing directly into an attached tmux pane.
+
+## Clean record versus raw history
+
+The clean record includes submissions whose semantic boundaries are known to a compatible client, plus explicit literate notes. Code typed directly into tmux is retained only in the raw pane/history mirror unless future runtime-specific instrumentation can establish reliable boundaries. Clients must not present raw `pipe-pane` output as reliably parsed code/output.
+
+Canonical Markdown exports identify origin, mode, status, runtime, and timestamp and include this direct-input limitation.
+
+## Optional raw-history display and alignment anchors
+
+Compatible clients may add protocol-independent submission displays to the raw pane while retaining the same clean record. Display version 1 derives a non-secret 12-hex-character anchor as the first 12 characters of SHA-256 over `pi-repl-submission-display-v1`, a NUL byte, and the stable clean-record entry ID. The entry ID itself is not written to the pane. The short hash is labelled `id:` in both the input and completion markers; it is a correlation aid, not an execution signal. The hash derivation and record protocol remain unchanged.
+
+Echo defaults and preview limits are client preferences, not protocol requirements. `pi-repl` defaults to **Summary**, which shows a short submission in full, truncating after 20 source lines or 2,000 source characters. **Off** writes no optional display or alignment anchors. Explicit opt-in **Full** raises the bounds to 40 lines or 4,000 characters. Both Summary and Full persist their source preview in raw terminal history; Off does not remove code from the clean record. Other clients, including older installations, may use different echo defaults or preview limits without affecting interoperability. Display text normalizes newlines and tabs, removes trailing display whitespace, and escapes terminal, line-separator, and bidirectional control characters.
+
+```text
+<runtime loader command>
+
+── pi-repl · input · 2 lines · id: a1b2c3d4e5f6 ──
+x = 1
+x + 1
+── output ──
+2
+── done · id: a1b2c3d4e5f6 ──
+
+<runtime prompt>
+```
+
+The compact submitted and completion anchors remain in raw tmux history for human readability and deterministic future alignment. A plain unanchored `── output ──` divider separates the source preview from runtime output without repeating the ID or other metadata. `pi-repl` inserts one display-only blank line before the begin anchor and after the completion anchor in Summary and Full modes, with no internal padding. The trailing gap is removed from clean output along with the exact final anchor; additional user whitespace is preserved. Native prompt spacing is not changed. Input previews are plain code without an added vertical bar. Cleanup matches the known preview before its output divider, including retained line wraps, so marker-looking lines inside source are not mistaken for real boundaries. Existing histories with different spacing, bar-prefixed source, unlabelled compact IDs or earlier three-marker displays remain readable. Clients remove the exact request-specific header, source preview, divider, and footer from captured tool output and clean-record output. These markers are presentation metadata, not clean-record authority: missing, malformed, duplicated, or user-produced marker-like text must never cause inferred raw activity to be promoted silently into protocol-v1 entries.
+
+## Runtime control files (outside protocol v1)
+
+Runtime-specific source wrappers and completion files are client implementation details, not shared-record state or authority. Compatible clients use compact request-unique names under a current-user-owned mode-`0700` `/tmp/pi-rc-<user-key>` root on POSIX systems, with mode-`0600` source files created exclusively. This avoids both verbose per-session paths and fixed global filenames that can collide across clients, processes, tmux servers, or runtimes.
+
+`pi-repl` prefixes submission control filenames with the display anchor: `<12-hex-anchor>-<16-hex-random-token>.<extension>`. Related source, guard and driver files share the anchor but retain independently allocated random tokens; each completion file uses its source file's full stem with `.done`. The prefix is present even in Off mode, without adding optional display markers. Transient paste-buffer files and callers that do not supply an anchor retain the older `<16-hex-random-token>.<extension>` form. Cleanup and stale-file pruning recognize both forms. The anchor derivation, record IDs and protocol version do not change; the prefix is only a human correlation aid, not a uniqueness guarantee or completion signal. Other clients need not adopt these names to remain compatible.
+
+A client removes the source and completion files after output capture. If a send times out or is aborted after submission, the same watcher that retains any shared lease also retains those files until the wrapper signals completion or the exact session lifetime disappears. Orphans left by a process crash are pruned after 24 hours on a later send. These files remain protocol-independent: their names and presence never turn raw pane activity into a clean-record entry.
+
+gnuplot's implementation additionally uses its guard's `.done` path as a private acknowledgment that the nested source returned. The pipe producer writes the source's actual completion file only after acknowledgment or native pipe closure on error/interruption. Neither a display marker, a comment written to the pipe, nor SIGINT alone establishes completion. This does not change the shared record or its lease protocol; source, guard and producer files are all retained until settlement.
+
+New gnuplot sessions also have independent launch-ownership metadata: the inherited `PI_REPL_GNUPLOT_OWNER` environment marker and matching tmux `@pi_repl_gnuplot_owner` option (32 lowercase hexadecimal characters). These are allocated only for a newly created session, not derived from a record ID, copied to another session, or retrofitted into a running interpreter. They support explicit-stop attribution of detached helpers together with UID/birth identities and pane protections. They are not record identity, send-lease authority or completion signals, and do not change protocol version 1. Clients without that attribution must report detached-helper cleanup as unverified rather than infer ownership from a process name or PID.
+
+C++ (`cpp`) likewise leaves record/display/lease version 1 unchanged. A private `.cpp` source, length-framed `.req` and ordinary C++ `.hxx` driver share the display anchor but have independent allocation tokens. The single terminal include loads an in-session Cling helper and a unique scalar initializer for this request; no completion command is queued into terminal stdin. The helper validates the private directory and request/source descriptor identities and publishes a `pi-repl-cpp-v1 <source-stem> <result>\n` reply only after native evaluation and helper-local destruction. Only a bounded, complete, single-link, owned mode-0600 reply in the original mode-0700 directory settles the send. Empty, malformed or mismatched replies remain pending. This is a native-return signal, not proof of successful library calls or rollback of earlier groups. Captured entries retain native diagnostics; tool details expose the evaluator result separately. The private controls are not a security sandbox against arbitrary code executing with the same user's privileges.
+
+## Compatibility
+
+A client that sees an unsupported version leaves it untouched. Existing tmux sessions gain v1 metadata lazily when inspected or used. Studio may import legacy browser-local entries as `pi-studio` entries using their stable IDs, making retries idempotent.

package/dist/shared/repl-control-files.js

@@ -0,0 +1,170 @@
+import { randomBytes } from "node:crypto";
+import {
+	chmodSync,
+	closeSync,
+	existsSync,
+	fchmodSync,
+	lstatSync,
+	mkdirSync,
+	openSync,
+	readdirSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+const REPL_CONTROL_TOKEN_BYTES = 8;
+const REPL_CONTROL_FILENAME_PATTERN = /^((?:[a-f0-9]{12}-)?[a-f0-9]{16})\.[A-Za-z0-9]{1,8}$/;
+const REPL_CONTROL_STALE_MS = 24 * 60 * 60 * 1_000;
+const prunedRoots = new Set();
+
+function currentUid() {
+	return typeof process.getuid === "function" ? process.getuid() : null;
+}
+
+export function getPrivateReplControlRoot() {
+	const uid = currentUid();
+	const base = process.platform === "win32" ? tmpdir() : "/tmp";
+	const userKey = uid === null ? "user" : uid.toString(36);
+	return join(base, `pi-rc-${userKey}`);
+}
+
+function assertPrivateReplControlRoot(root) {
+	const stats = lstatSync(root);
+	if (!stats.isDirectory() || stats.isSymbolicLink()) {
+		throw new Error(`REPL control root is not a real directory: ${root}`);
+	}
+	const uid = currentUid();
+	if (uid !== null && stats.uid !== uid) {
+		throw new Error(`REPL control root is not owned by the current user: ${root}`);
+	}
+	if (process.platform !== "win32" && (stats.mode & 0o777) !== 0o700) {
+		throw new Error(`REPL control root must have mode 0700: ${root}`);
+	}
+}
+
+function getReplControlFileStem(name) {
+	const match = name.match(REPL_CONTROL_FILENAME_PATTERN);
+	return match?.[0] === name ? match[1] : undefined;
+}
+
+function pruneStaleReplControlFiles(root, now = Date.now()) {
+	if (prunedRoots.has(root)) return;
+	prunedRoots.add(root);
+	let entries = [];
+	try {
+		entries = readdirSync(root);
+	} catch {
+		return;
+	}
+	const uid = currentUid();
+	for (const entry of entries) {
+		if (!getReplControlFileStem(entry)) continue;
+		const file = join(root, entry);
+		try {
+			const stats = lstatSync(file);
+			if (!stats.isFile() || stats.isSymbolicLink()) continue;
+			if (uid !== null && stats.uid !== uid) continue;
+			if (now - stats.mtimeMs < REPL_CONTROL_STALE_MS) continue;
+			unlinkSync(file);
+		} catch {
+			// Another process may have removed the same stale file.
+		}
+	}
+}
+
+export function ensurePrivateReplControlRoot(root = getPrivateReplControlRoot()) {
+	let created = false;
+	try {
+		mkdirSync(root, { mode: 0o700 });
+		created = true;
+	} catch (error) {
+		if (!error || typeof error !== "object" || error.code !== "EEXIST") throw error;
+	}
+	if (created && process.platform !== "win32") chmodSync(root, 0o700);
+	assertPrivateReplControlRoot(root);
+	pruneStaleReplControlFiles(root);
+	return root;
+}
+
+function normalizeExtension(extension) {
+	const normalized = String(extension || "").replace(/^\.+/, "");
+	if (!normalized || normalized.length > 8 || /[^A-Za-z0-9]/.test(normalized)) {
+		throw new Error(`Invalid REPL control-file extension: ${extension}`);
+	}
+	return normalized;
+}
+
+/**
+ * Create and populate one private, collision-resistant REPL control file.
+ * An optional display anchor prefixes the independent random allocation token.
+ * The builder receives the final paths so it can embed the matching done-file
+ * path in the runtime-specific wrapper.
+ */
+export function createPrivateReplControlFiles(options) {
+	const extension = normalizeExtension(options?.extension);
+	const anchorId = options?.anchorId;
+	if (anchorId !== undefined && (typeof anchorId !== "string" || anchorId.length !== 12 || !/^[a-f0-9]{12}$/.test(anchorId))) {
+		throw new Error("Invalid REPL submission anchor ID: expected 12 lowercase hex characters.");
+	}
+	const prefix = anchorId === undefined ? "" : `${anchorId}-`;
+	const root = ensurePrivateReplControlRoot(options?.root || getPrivateReplControlRoot());
+	if (typeof options?.buildSource !== "function") {
+		throw new Error("REPL control-file source builder is required.");
+	}
+
+	for (let attempt = 0; attempt < 20; attempt += 1) {
+		const stem = prefix + randomBytes(REPL_CONTROL_TOKEN_BYTES).toString("hex");
+		const paths = {
+			dir: root,
+			sourceFile: join(root, `${stem}.${extension}`),
+			doneFile: join(root, `${stem}.done`),
+		};
+		if (existsSync(paths.doneFile)) continue;
+
+		let descriptor;
+		try {
+			descriptor = openSync(paths.sourceFile, "wx", 0o600);
+		} catch (error) {
+			if (error && typeof error === "object" && error.code === "EEXIST") continue;
+			throw error;
+		}
+
+		let complete = false;
+		try {
+			const source = String(options.buildSource(paths));
+			writeFileSync(descriptor, source, "utf8");
+			if (process.platform !== "win32") fchmodSync(descriptor, 0o600);
+			complete = true;
+			return paths;
+		} finally {
+			closeSync(descriptor);
+			if (!complete) {
+				try {
+					unlinkSync(paths.sourceFile);
+				} catch {
+					// Preserve the source-builder error.
+				}
+			}
+		}
+	}
+	throw new Error("Could not allocate a unique REPL control file.");
+}
+
+export function cleanupPrivateReplControlFiles(paths) {
+	if (!paths || typeof paths !== "object") return;
+	const root = String(paths.dir || "");
+	const sourceFile = String(paths.sourceFile || "");
+	const doneFile = String(paths.doneFile || "");
+	const sourceName = basename(sourceFile);
+	const stem = getReplControlFileStem(sourceName);
+	if (!stem || dirname(sourceFile) !== root || dirname(doneFile) !== root || basename(doneFile) !== `${stem}.done`) return;
+	for (const file of [sourceFile, doneFile]) {
+		try {
+			unlinkSync(file);
+		} catch {
+			// Cleanup is idempotent and best effort.
+		}
+	}
+}

package/dist/shared/repl-cpp-driver.hxx

@@ -0,0 +1,164 @@
+// Cling-only, in-session driver. No evaluator process, source rewriting or replay.
+// Included by the first private driver; this reserved namespace is protocol v1.
+#ifndef PI_REPL_CPP_DRIVER_V1
+#define PI_REPL_CPP_DRIVER_V1
+#include <cling/Interpreter/Interpreter.h>
+#include <cling/Interpreter/RuntimeUniverse.h>
+#include <cling/MetaProcessor/InputValidator.h>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <string>
+#include <exception>
+#include <stdexcept>
+#include <cerrno>
+#include <climits>
+#include <fcntl.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+namespace pi_repl_cpp_v1 {
+using number = unsigned long long;
+struct file {
+  int fd;
+  explicit file(int value) : fd(value) {}
+  void close_now() { if (fd >= 0) { close(fd); fd=-1; } }
+  ~file() { close_now(); }
+  file(const file&) = delete;
+};
+inline bool decimal(const std::string& text, number& value) {
+  if (text.empty() || text.size() > 20) return false;
+  value = 0;
+  for (char c : text) {
+    if (c < '0' || c > '9' || value > (ULLONG_MAX - (c-'0')) / 10) return false;
+    value = value * 10 + (c-'0');
+  }
+  return true;
+}
+inline bool stem_ok(const std::string& text) {
+  if (text.size() != 16 && text.size() != 29) return false;
+  for (size_t i=0; i<text.size(); ++i) {
+    char c=text[i];
+    if (text.size()==29 && i==12) { if (c!='-') return false; }
+    else if (!((c>='0' && c<='9') || (c>='a' && c<='f'))) return false;
+  }
+  return true;
+}
+inline bool private_file(int fd, number dev, number ino, number size) {
+  struct stat s;
+  return fd>=0 && fstat(fd,&s)==0 && S_ISREG(s.st_mode)
+    && s.st_uid==getuid() && (s.st_mode&0777)==0600 && s.st_nlink==1
+    && number(s.st_dev)==dev && number(s.st_ino)==ino && number(s.st_size)==size;
+}
+inline bool read_exact(int fd, number size, std::string& result) {
+  char buffer[4096];
+  while (size) {
+    ssize_t n=read(fd,buffer,size<sizeof buffer ? size : sizeof buffer);
+    if (n<0 && errno==EINTR) continue;
+    if (n<=0) return false;
+    result.append(buffer,size_t(n)); size-=number(n);
+  }
+  // Reject growth as well as truncation; never read unbounded user input.
+  char extra; return read(fd,&extra,1)==0;
+}
+inline bool field(const std::string& request, size_t& position, std::string& result) {
+  size_t end=request.find('\n',position); number size;
+  if (end==std::string::npos || !decimal(request.substr(position,end-position),size)
+      || size>request.size()-end-1) return false;
+  position=end+1; result=request.substr(position,size); position+=size; return true;
+}
+inline int evaluate(const std::string& source) {
+  cling::InputValidator validator;
+  int result=0; size_t position=0;
+  while (position<source.size()) {
+    size_t end=source.find('\n',position);
+    std::string line=source.substr(position,end==std::string::npos ? end : end-position);
+    position=end==std::string::npos ? source.size() : end+1;
+    if (validator.validate(line)==cling::InputValidator::kIncomplete) { result=2; continue; }
+    std::string input; validator.reset(&input);
+    result=static_cast<int>(cling::runtime::gCling->process(input));
+    if (result!=0) break;
+  }
+  if (result==2) fputs("pi-repl: incomplete C++ prompt group; no continuation is queued\n",stderr);
+  return result;
+}
+inline void submit(const char* request_path, number root_dev, number root_ino,
+                   number request_dev, number request_ino, number request_size) {
+  static const pid_t owner_pid = getpid();
+  int response_fd=-1;
+  char reply[128]; size_t reply_size=0;
+  {
+  // All descriptors and source/evaluator locals die before publication.
+  // Source/request failure before a valid family is decoded fails closed.
+  std::string root_path, stem, footer;
+  int result=5;
+  try {
+    std::string path(request_path);
+    size_t slash=path.rfind('/');
+    if (slash==std::string::npos || request_size>65536) throw std::runtime_error("invalid request path or size");
+    root_path=path.substr(0,slash);
+    std::string name=path.substr(slash+1);
+    if (name.size()<5 || name.substr(name.size()-4)!=".req" || !stem_ok(name.substr(0,name.size()-4))) throw std::runtime_error("invalid request name");
+    file root(open(root_path.c_str(),O_RDONLY|O_DIRECTORY|O_NOFOLLOW|O_CLOEXEC));
+    struct stat rs;
+    if (root.fd<0 || fstat(root.fd,&rs)!=0 || rs.st_uid!=getuid() || (rs.st_mode&0777)!=0700
+        || number(rs.st_dev)!=root_dev || number(rs.st_ino)!=root_ino) throw std::runtime_error("private directory changed");
+    file request(openat(root.fd,name.c_str(),O_RDONLY|O_NOFOLLOW|O_NONBLOCK|O_CLOEXEC));
+    std::string body;
+    if (!private_file(request.fd,request_dev,request_ino,request_size) || !read_exact(request.fd,request_size,body)) throw std::runtime_error("request identity or read failed");
+    const std::string magic="pi-repl-cpp-v1\n";
+    if (body.compare(0,magic.size(),magic)!=0) throw std::runtime_error("unknown request protocol");
+    size_t position=magic.size(); std::string fields[6];
+    for (auto& value : fields) if (!field(body,position,value)) throw std::runtime_error("invalid request frame");
+    number dev,ino,size;
+    if (position!=body.size() || !stem_ok(fields[0]) || !decimal(fields[1],dev)
+        || !decimal(fields[2],ino) || !decimal(fields[3],size) || size>16*1024*1024
+        || fields[5].find('\0')!=std::string::npos) throw std::runtime_error("invalid request fields");
+    stem=fields[0]; footer=fields[5];
+    file source_file(openat(root.fd,(stem+".cpp").c_str(),O_RDONLY|O_NOFOLLOW|O_NONBLOCK|O_CLOEXEC));
+    std::string source;
+    if (!private_file(source_file.fd,dev,ino,size) || !read_exact(source_file.fd,size,source)
+        || source.find('\0')!=std::string::npos) throw std::runtime_error("source identity or read failed");
+    // Do not keep control descriptors in the user's running workspace. A user
+    // closing/reusing a descriptor must not make our later destructor close it.
+    source_file.close_now(); request.close_now(); root.close_now();
+    fwrite(fields[4].data(),1,fields[4].size(),stderr); fflush(stderr);
+    try { result=evaluate(source); }
+    catch (const std::exception& error) {
+      fprintf(stderr,"pi-repl caught std::exception: %s\n",error.what()); result=3;
+    } catch (...) { fputs("pi-repl caught non-standard C++ exception\n",stderr); result=4; }
+  } catch (const std::exception& error) {
+    fprintf(stderr,"pi-repl C++ control error: %s\n",error.what());
+  } catch (...) { fputs("pi-repl C++ control error\n",stderr); }
+  fflush(stdout); fflush(stderr);
+  if (getpid()!=owner_pid || stem.empty()) return;
+  // Like the other native adapters, the optional display uses existing Node
+  // and a bounded read-only cursor query. It is NOT completion authority.
+  if (!footer.empty() && std::system(footer.c_str())!=0) fputs("\n",stderr);
+  fflush(stdout); fflush(stderr);
+  file root(open(root_path.c_str(),O_RDONLY|O_DIRECTORY|O_NOFOLLOW|O_CLOEXEC));
+  struct stat rs;
+  if (root.fd<0 || fstat(root.fd,&rs)!=0 || rs.st_uid!=getuid() || (rs.st_mode&0777)!=0700
+      || number(rs.st_dev)!=root_dev || number(rs.st_ino)!=root_ino) return;
+  response_fd=openat(root.fd,(stem+".done").c_str(),O_WRONLY|O_CREAT|O_EXCL|O_NOFOLLOW|O_CLOEXEC,0600);
+  if (response_fd<0 || fchmod(response_fd,0600)!=0) {
+    perror("pi-repl C++ response"); if (response_fd>=0) close(response_fd); return;
+  }
+  int count=snprintf(reply,sizeof reply,"pi-repl-cpp-v1 %s %d\n",stem.c_str(),result);
+  if (count<0 || size_t(count)>=sizeof reply) { close(response_fd); return; }
+  reply_size=size_t(count);
+  } // Every helper-owned C++ object is destroyed before the reply is written.
+  // Empty/partial frames are pending. No destructor or user source follows this
+  // publication, only POSIX write/close and the driver's scalar initialization.
+  if (getpid()!=owner_pid) { close(response_fd); return; }
+  size_t written=0;
+  while (written<reply_size) {
+    ssize_t n=write(response_fd,reply+written,reply_size-written);
+    if (n<0 && errno==EINTR) continue;
+    if (n<=0) break;
+    written+=size_t(n);
+  }
+  close(response_fd);
+}
+}
+#endif

package/dist/shared/repl-cpp.js

@@ -0,0 +1,107 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, unlinkSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const CPP_DRIVER_HEADER = fileURLToPath(new URL("./repl-cpp-driver.hxx", import.meta.url));
+export const CPP_MAX_SOURCE_BYTES = 16 * 1024 * 1024;
+const stemPattern = /^(?:[a-f0-9]{12}-)?[a-f0-9]{16}$/;
+
+// Fixed-width octal encodes UTF-8 without C++ hex-escape run-on or terminal input.
+export function cppStringLiteral(value) {
+	return '"' + [...Buffer.from(String(value), "utf8")].map((b) => `\\${b.toString(8).padStart(3, "0")}`).join("") + '"';
+}
+function quote(value) { return `'${value.replace(/'/g, `'"'"'`)}'`; }
+function privateStat(path, directory = false) {
+	const s = lstatSync(path, { bigint: true });
+	if (!(directory ? s.isDirectory() : s.isFile()) || s.isSymbolicLink()
+		|| s.uid !== BigInt(process.getuid()) || (s.mode & 0o777n) !== (directory ? 0o700n : 0o600n)
+		|| (!directory && s.nlink !== 1n)) throw new Error(`Unsafe C++ control path: ${path}`);
+	return s;
+}
+export function buildCppRequest(sourceFile, doneFile, display) {
+	const stem = basename(sourceFile, ".cpp");
+	if (!stemPattern.test(stem) || stem.length !== stem.match(stemPattern)?.[0].length
+		|| basename(doneFile) !== `${stem}.done` || dirname(sourceFile) !== dirname(doneFile)) throw new Error("Invalid C++ control family.");
+	const s = privateStat(sourceFile);
+	if (s.size > BigInt(CPP_MAX_SOURCE_BYTES)) throw new Error("C++ submission exceeds the 16 MiB source limit; no code was sent.");
+	const footer = [
+		'let column = "";',
+		'try { column = require("node:child_process").execFileSync("tmux", ["-N", "display-message", "-p", "-t", process.env.TMUX_PANE, "#{cursor_x}"], { encoding: "utf8", timeout: 500, killSignal: "SIGKILL", maxBuffer: 128, stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}',
+		`process.stderr.write((column === "0" ? "" : "\\n") + ${JSON.stringify(display.enabled ? display.suffixLines.join("\n") + "\n" : "")});`,
+	].join(" ");
+	// Length framing, not executable C++/JSON interpolation. Names are relative
+	// to a pinned private directory, and source inode/size are checked natively.
+	const fields = [stem, String(s.dev), String(s.ino), String(s.size), display.enabled ? display.prefixLines.join("\n") + "\n" : "", `${quote(process.execPath)} -e ${quote(footer)}`];
+	return "pi-repl-cpp-v1\n" + fields.map((s) => `${Buffer.byteLength(s)}\n${s}`).join("");
+}
+export function cppInclude(path) {
+	if (/[\x00-\x1f\x7f\u2028\u2029]/.test(path)) throw new Error("C++ include paths cannot contain control characters, line breaks or NUL bytes.");
+	if (!path.includes(">")) return `#include <${path}>`;
+	if (!path.includes('"')) return `#include "${path}"`;
+	throw new Error("C++ include paths cannot contain both double quotes and >.");
+}
+export function buildCppDriverSource(requestFile, doneFile) {
+	const { submissionLine } = prepareCppSubmission(requestFile, doneFile);
+	const name = basename(requestFile, ".req").replaceAll("-", "_");
+	if (!/^[a-f0-9_]+$/.test(name)) throw new Error("Invalid C++ driver name.");
+	// A unique, ordinary C++ initializer, NOT Cling's top-level-statement
+	// extension. Each include runs this request once; no stdin command follows.
+	return `${cppInclude(CPP_DRIVER_HEADER)}\nnamespace pi_repl_cpp_v1 { const int request_${name} = (${submissionLine.slice(0, -1)}, 0); }\n`;
+}
+export function prepareCppSubmission(requestFile, doneFile) {
+	if (dirname(requestFile) !== dirname(doneFile)) throw new Error("C++ controls must share one private directory.");
+	const root = privateStat(dirname(requestFile), true);
+	const request = privateStat(requestFile);
+	return {
+		submissionLine: `pi_repl_cpp_v1::submit(${cppStringLiteral(requestFile)}, ${root.dev}ULL, ${root.ino}ULL, ${request.dev}ULL, ${request.ino}ULL, ${request.size}ULL);`,
+		completion: { doneFile, rootDev: String(root.dev), rootIno: String(root.ino), stem: basename(doneFile, ".done") },
+	};
+}
+
+export function createCppControlCleanup(completion, paths) {
+	const files = paths.map((path) => ({ path, stat: privateStat(path) }));
+	return () => {
+		try {
+			const root = privateStat(dirname(completion.doneFile), true);
+			if (String(root.dev) !== completion.rootDev || String(root.ino) !== completion.rootIno) return;
+		} catch { return; }
+		for (const { path, stat } of files) {
+			try {
+				const current = privateStat(path);
+				if (current.dev === stat.dev && current.ino === stat.ino && current.size === stat.size) unlinkSync(path);
+			} catch { /* Absent or changed controls are never adopted for cleanup. */ }
+		}
+		if (readCppCompletion(completion) !== undefined) {
+			try { unlinkSync(completion.doneFile); } catch {}
+		}
+	};
+}
+
+// Presence, prompts and display IDs are not settlement. Partial/malformed,
+// symlinked, multiply-linked or replaced-root replies remain pending.
+export function readCppCompletion(completion) {
+	let fd;
+	try {
+		const { doneFile, rootDev, rootIno, stem } = completion;
+		const root = privateStat(dirname(doneFile), true);
+		if (String(root.dev) !== rootDev || String(root.ino) !== rootIno) return undefined;
+		const before = privateStat(doneFile);
+		if (before.size > 128n) return undefined;
+		fd = openSync(doneFile, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+		const opened = fstatSync(fd, { bigint: true });
+		if (opened.dev !== before.dev || opened.ino !== before.ino || opened.size !== before.size
+			|| !opened.isFile() || opened.uid !== BigInt(process.getuid()) || opened.nlink !== 1n || (opened.mode & 0o777n) !== 0o600n) return undefined;
+		const buffer = Buffer.alloc(129);
+		const count = readSync(fd, buffer, 0, buffer.length, 0);
+		if (BigInt(count) !== opened.size) return undefined;
+		const text = buffer.subarray(0, count).toString("utf8");
+		const after = privateStat(doneFile);
+		if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size) return undefined;
+		const finalRoot = privateStat(dirname(doneFile), true);
+		if (String(finalRoot.dev) !== rootDev || String(finalRoot.ino) !== rootIno) return undefined;
+		const match = text.match(/^pi-repl-cpp-v1 ([a-f0-9-]+) ([0-5])\n$/);
+		if (!match || match[0] !== text || match[1] !== stem) return undefined;
+		return Number(match[2]);
+	} catch { return undefined; }
+	finally { if (fd !== undefined) closeSync(fd); }
+}