Reference Manual
Reference Manual
Applies to Terminux 0.1.1. Commands and features may differ in other versions.
Contents
- About this manual
- System overview
- Command reference
- Terminux terminal (GUI) reference
- DQE Viewer reference
- @@ reference
- Configuration reference
- Files and data reference
- Quality checks (DQE) reference
- Messages and codes
- Limits, timeouts and defaults
- Glossary
1. About this manual
1.1 Notation
| Notation | Meaning |
|---|---|
<value> |
Required; replace with an actual value |
[option] |
Optional |
a|b |
One of the alternatives |
… |
Repeatable, or the rest omitted |
~ |
Your home directory |
<nodename> |
The host name (overridable with TERMINUX_NODENAME) |
1.2 Where the commands are
- Source installation: in the
bin/of the Python environment (for example$VIRTUAL_ENV/bin/). - Portable bundle:
~/.local/bincontains onlyterminux(=terminux-launch) andterminux-qt-check; the other commands are in~/.local/opt/terminux/current/venv/bin/. - Scripts in the source tree:
terminux-chat,terminux-dream,terminux-lineage-graph,terminux-build-rag-indexandterminux-llm-env.sh/.cshare in thescripts/directory of the source tree.
2. System overview
| Component | Description |
|---|---|
| Daemon | The background service, one per Linux account. All data, AI and execution management live here. Uniqueness is guaranteed by the owner lock (~/.terminux/run/owner.lock) |
| Core socket | ~/.terminux/run/<nodename>/terminux.sock: the connection on which the GUI and CLIs open a session |
| Lineage socket | ~/.terminux/run/<nodename>/lineage.sock: lineage checks, @@, the DQE Viewer, tasks and other requests |
GUI (terminux) |
The terminal window; it never starts the daemon itself, terminux-launch does |
DQE Viewer (dqe_viewer) |
Started locally by the GUI; reads data through the lineage socket |
| Shell hooks and wrappers | Installed into ~/.terminux when the daemon starts; they notify the daemon when commands start and end |
Relay (terminux-relay) |
Local relay on hosts that are not the owner, when several hosts share HOME (not verified) |
The daemon accepts connections only from the same Linux account; the identity of a connection is checked by the operating system.
3. Command reference
3.1 terminux-launch
Synopsis: terminux-launch [--no-gui] [--reset] [--version]
Starts or reuses the daemon, then starts the GUI. In the portable bundle, ~/.local/bin/terminux is this command.
| Option | Description |
|---|---|
| (none) | Make sure the daemon is running, then open the GUI |
--no-gui |
Only make sure the daemon (or relay) is running; do not open the GUI |
--reset |
Print owner.json, ask you to type yes, then remove only ~/.terminux/run/owner.lock. No daemon is stopped |
--version |
Print the version and exit |
Behavior:
| Owner state | Action |
|---|---|
| No owner | Start the daemon in the background (output to daemon.stdout.log) and wait up to 30 seconds for it to become ready; on timeout only warn and open the GUI anyway |
| Owner starting | Wait up to 30 seconds |
| Owner on this host, process alive | Reuse it |
| Owner on this host, process gone | Start the daemon again (the daemon reclaims the stale lock itself) |
| Owner on another host | Check that the owner's TCP port can be reached within 3 seconds, then start a local relay (not verified) |
| Owner state not ready, unreadable, or unix-only on another host | Fail (TERM_DAEMON_OWNER_UNAVAILABLE) |
| You are in Profile mode but the owner was not started in Profile mode | Fail (TERM_DAEMON_OWNER_UNCONTAINED); the owner is neither reused nor stopped |
The GUI is searched in this order: TERMINUX_GUI_BIN → <Python environment>/bin/terminux → <Python environment>/../bin/terminux
→ an ELF executable on PATH (the launcher itself is skipped). If none is found: TERM_LAUNCH_GUI_NOT_FOUND. When the daemon
failed to deploy the hooks, or the deployment is disabled, TERM_LAUNCH_WRAPPER_SETUP is printed.
Exit codes: 0 success; 1 failure (messages start with TERM_, see chapter 10).
3.2 terminux (GUI)
Synopsis: terminux [--version] [--self-check] (source installation; for the bundle's terminux see 3.1)
| Option | Description |
|---|---|
| (none) | Open the Terminux terminal window |
--version |
Print the version and license, then exit |
--self-check |
Start in offscreen mode, check Qt and its plugins, then exit; no window, no daemon connection |
After start-up the GUI connects to the Core socket and retries every 3 seconds while it cannot connect.
3.3 terminux-daemon
Synopsis: terminux-daemon [--version] [-h|--help]; equivalent to python -m terminux_engine
Normally started by terminux-launch. All settings come from the environment variables at start-up
(7.2).
Exit codes: 0 normal stop (SIGINT/SIGTERM received); 2 the socket paths cannot be resolved (TERM_AGENT_SOCKET_UNAVAILABLE);
3 start-up failed (TERM_SERVICE_START_FAILED); 4 an owner already exists or a legacy daemon was detected
(TERM_DAEMON_OWNER_EXISTS, TERM_LEGACY_DAEMON_RUNNING).
python -m terminux_engine.maindoes not start the daemon; it exits immediately.
3.4 python -m terminux_engine purge
Synopsis: python -m terminux_engine purge --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--force]
Removes the events of a date range from the event records (~/.terminux/ecc/event_store.db). Run it while the daemon is
stopped.
| Option | Description |
|---|---|
--from, --to |
First and last date (inclusive) |
--force |
Really delete. The events of the range are first written as JSONL to ~/.terminux/ecc/archive/ and fsynced; only then are they deleted. Allowed only for the account in TERMINUX_PURGE_ALLOW_USER (default: the current account) |
(without --force) |
Only preview the number of affected events; the database is not changed |
Exit codes: 0 success; 1 --force refused; 2 invalid arguments; 5 the daemon runs on another host (TERM_DATABASE_REMOTE_OWNER).
3.5 terminux-relay (not verified)
Synopsis: terminux-relay (no options; normally started by terminux-launch)
Provides the local Core and lineage sockets on a host that is not the owner, reads owner.json for every connection and
connects to the owner's TCP ports with a token. A single instance is guaranteed by ~/.terminux/run/<nodename>/relay.pid;
the log is relay.log in the same directory.
3.6 terminux-doctor
Synopsis: terminux-doctor [--agent-socket <path>] [--lineage-socket <path>] [--version]
Local diagnostics; calls no provider, runs no EDA tool, and never reads the content of the credentials file. Output is JSON:
| Field | Content |
|---|---|
package_version |
Package version |
agent_socket, lineage_socket |
Paths of the two sockets |
daemon |
running, state, host, pid |
llm_config |
Whether the legacy Layer 2 configuration exists and is readable, and its source (package template or user) |
bundled_knowledge |
Whether the five bundled knowledge files are readable |
plugin_dir |
Whether the plugin directory exists (0.1.x ships no plugins, so its absence is normal) |
eap3_bindings |
State of the Engineering Work bindings file (when configured) |
credentials |
Source of the credentials file and whether it is safe (owned by you, 0600, regular file); the content is not read |
background |
Whether background RAG rebuilding is disabled; the embedding backend |
status |
ready or attention |
Exit codes: 0 ready; 1 attention.
3.7 terminux-qt-check
Synopsis: terminux-qt-check --qt-dir <Qt directory> [--prefix <installation prefix>]
Reads an external Qt installation and checks its version, libraries, QML imports and the xcb and offscreen plugins. With
--prefix, it also runs the self-checks of terminux and dqe_viewer in offscreen mode (no window, no daemon connection).
When xcb is missing system libraries, it lists the SONAMEs and the known EL9/Ubuntu 24.04 package names, but never installs
anything. On multiple hosts, the Qt directory must have the same absolute path on every host.
Exit codes: 0 passed; 1 failed.
3.8 terminux-orfs-run
Synopsis:
terminux-orfs-run --orfs-repo-root <dir> --work-home <dir> --design <name> --platform <name>
--variant <name> --design-config <path> --ledger-db <file> --receipt-out <file>
[--env-script <file>] [--make-executable <file>] [--openroad-exe <file>] [--yosys-exe <file>]
[--timeout-seconds <seconds>] [--receipt-store <file> | --no-receipt] [--version]
Runs one ORFS flow on the host under your account (host-native) and leaves a receipt, an artifact manifest and a quality verdict. Running it as root is refused.
| Option | Required | Default | Description |
|---|---|---|---|
--orfs-repo-root |
Yes | — | The ORFS installation root (containing flow/); may be read-only |
--work-home |
Yes | — | Output directory (ORFS WORK_HOME); must be owned by you; the last level is created if its parent exists |
--design |
Yes | — | Must equal the name ORFS uses for its output directories (DESIGN_NICKNAME, or DESIGN_NAME when not set) |
--platform |
Yes | — | For example nangate45 |
--variant |
Yes | — | ORFS FLOW_VARIANT; must not be base; becomes part of the step id orfs-<design>-<variant> |
--design-config |
Yes | — | Path of config.mk relative to ORFS flow/; must be under flow/ |
--ledger-db |
Yes | — | A ledger file dedicated to this run; must not point to the daemon's ~/.terminux/orchestration/ledger.sqlite (aliases included) |
--receipt-out |
Yes | — | Where to write the receipt JSON |
--env-script |
No | <orfs-repo-root>/env.sh |
Environment script that makes the EDA tools available; apart from HOME, LANG and PATH, the shell environment is not inherited |
--make-executable |
No | make on PATH |
The make that runs the flow |
--openroad-exe, --yosys-exe |
No | ORFS's own rules | Explicit ORFS OPENROAD_EXE, YOSYS_EXE |
--timeout-seconds |
No | 900 | Time limit in seconds |
--receipt-store |
No | TERMINUX_EVENT_STORE_PATH or ~/.terminux/ecc/event_store.db |
Write the receipt into the given event-record file instead |
--no-receipt |
No | — | Do not write into any event records (--receipt-out is still written); mutually exclusive with --receipt-store |
Output: at the end, stdout shows the quality summary and the run id; --work-home contains ORFS's results/, reports/,
logs/ and objects/; the receipt is written to --receipt-out. The tool identity (paths and SHA-256 of the env script,
make, the design configuration and any explicit tools) is recorded in the receipt.
Exit codes:
| Code | Meaning |
|---|---|
| 0 | The run succeeded and the receipt was written (with --no-receipt, only the run result counts) |
| 1 | The run failed (the quality verdict itself does not affect the exit code) |
| 2 | Invalid options or environment: running as root, a --work-home you do not own, a --ledger-db that points to the daemon's ledger, a missing env script or make, or the removed --docker-image |
| 3 | The run succeeded but the receipt was not written |
| 5 | The daemon runs on another host |
| 130/143 | Ctrl-C/SIGTERM received (not verified) |
The codes that may appear on stderr are listed in 10.3.
3.9 terminux-orfs-report
Synopsis: terminux-orfs-report --receipt <file> --run-id <run_id> --attempt <n> [--role <role>] [--stage <N> [--expect-line <L>] [--view]]
Prints a report only after its hash matches the receipt and the artifact manifest, so what you see is the report of that exact run.
| Option | Description |
|---|---|
--receipt, --run-id, --attempt |
Required |
--role |
orfs.finish_report (default) or orfs.route_drc_report |
--stage N |
Locate stage N (1-based) of the timing path in the finish report instead |
--expect-line L |
With --stage: require that stage to be on line L |
--view |
With --stage: open the verified report at that line with less -N (needs a terminal) |
Exit codes: 0 success; 2 error (message on stderr).
3.10 dqe_viewer
Normally started by the GUI on @@open DQE Viewer with --db, --temporary-db-path and --ipc-endpoint. To run it by hand:
Synopsis: dqe_viewer [options]
| Option | Description |
|---|---|
--version |
(As the last argument, without a value) print the version and exit |
--smoke-exit |
Build and validate the QML interface, then exit immediately (installation check) |
--ipc-endpoint <socket> |
The daemon's lineage socket; must be combined with a Temporary or Archived data source |
--temporary-db-path <file> |
Temporary data source (the quality database) |
--db <file> |
Compatibility alias for --temporary-db-path |
--archived-version-dir <dir> |
Archived data source |
--temporary-retention-days <days> |
Display context of the Temporary retention period (1–3650) |
--workspace archived|temporary|compare |
Initial workspace (--select-tab is a compatibility alias) |
--job-key <job_key> |
Focus this job in the Temporary workspace (needs a Temporary data source) |
--window-size <W>x<H> |
Window size, for example 1440x900 |
--screenshot <png> |
Take a screenshot when the interface is ready, then exit (needs a data source or a built-in sample scenario) |
--ui-scenario <name> |
Scenario of the built-in sample data (for screenshots and visual comparison) |
Without --ipc-endpoint and a data source, the Viewer shows the built-in sample data (marked MOCK on screen).
3.11 dqe-scheduled-clean
Synopsis: dqe-scheduled-clean [--db <file>] [--policy <file>] [--dry-run] [--no-vacuum] [--log <file>]
Removes expired jobs according to the Temporary retention policy.
| Option | Default | Description |
|---|---|---|
--db |
~/.terminux/dqe/dqe.sqlite |
The quality database |
--policy |
~/.terminux/dqe/retention_policy.json |
The retention policy |
--dry-run |
— | Only compute; delete nothing |
--no-vacuum |
— | Do not run SQLite VACUUM after deleting |
--log |
~/.terminux/dqe/scheduled_clean.log |
The log file |
Output is JSON. Exit codes: 0 success; 1 failure; 2 invalid arguments; 3 completed, but the retention policy file was invalid or had a warning and the default policy was used; 5 the daemon runs on another host.
3.12 terminux-cold-backup
Synopsis:
terminux-cold-backup [--agent-socket <path>] [--lineage-socket <path>] create <destination> --source <LABEL>=<abs path> …
terminux-cold-backup verify <backup>
terminux-cold-backup restore <backup> --target <LABEL>=<abs path> …
| Subcommand | Rules |
|---|---|
create |
The daemon must be stopped (no owner lock); the destination must be an absolute path that does not exist; sources are LABEL=/absolute/path (LABEL: letters, digits, _, - only), must not overlap, must not contain symlinks or special files, and must not contain the destination |
verify |
Recomputes the SHA-256 of every file and compares it with the backup record |
restore |
The daemon must be stopped; the set of target LABELs must equal the backup's, each path must equal the original path at backup time and must not exist now; files are first written to a staging directory and checked against their hashes, then moved into place |
Output is JSON. Exit codes: 0 success; 2 a precondition is not met ({"status": "error", "reason": …}). --help only.
3.13 terminux-rollback-check
Synopsis: terminux-rollback-check --event-store <file> --agent-socket <path> --lineage-socket <path>
Checks, in a read-only transaction, whether the data formats in the event records are within the range this version
supports: Engineering Work engineering_work.v1, and FlowTask and AnalysisTask schema 1 and 2. It neither switches programs
nor restores data. Output is JSON.
Exit codes: 0 compatible (DATA_COMPATIBLE_ONLY); 2 incompatible or unreadable (REJECTED); 5 the daemon runs on another
host. --help only.
3.14 terminux-work (not verified)
Synopsis: terminux-work [--agent-socket <path>] [--lineage-socket <path>] [--project <id>] [--profile-path <file>] <subcommand> …
| Subcommand | Arguments | Description |
|---|---|---|
create |
<profile_id> <package_id> <objective>; [--block] [--method] [--source-root] [--criterion …] [--constraint …] [--expert …] [--review proposal_review|result_review …] |
Create a work item |
create-from-saved-proposal |
<profile_id> <source_work_id> <source_proposal_id> <expected_proposal_digest> <objective>; [--source-root] [--criterion …] [--constraint …] [--request-id] |
Create a work item from a previously saved proposal |
authorize |
<work_id>; [--mode PLAN_ONLY|PER_PROPOSAL|BOUNDED_EXPLORATION] (default BOUNDED_EXPLORATION) [--attempts 2] [--provider-dispatches 12] [--tool-launches 5] [--candidate-materializations 2] [--formal-proof-launches N] [--baseline-tool-launches N] [--allowed-method …] [--allowed-change-json …] [--writable-root …] [--stop-condition …] |
Authorization preview (scope and limits) |
approve, continue, get, pause, resume, cancel, takeover |
<work_id> |
Approve, advance, show, pause, resume, cancel, take over again |
config |
<work_id> |
Show the settings actually in effect for this work item |
export |
<work_id> |
Print a support summary (JSON) with sensitive content masked by default, for reporting problems |
list |
— | List work items |
answer |
<work_id> <message>; [--objective] [--method] |
Answer a question or add information |
Needs TERMINUX_EAP3_BINDINGS_FILE; without it, or in Profile mode, the feature is not enabled. --profile-path first
selects a Profile for this session. Exit codes: 0 success; 2 error.
3.15 terminux-tool (not verified)
Synopsis: terminux-tool [--format text|json] register <tool_id> [--executable <name> …], … unregister <tool_id>, … list
Registers your own EDA executables (no administrator rights needed) in ~/.terminux/tools/user_tool_catalog.yaml.
--executable can be repeated and defaults to the tool id. list shows built-in and user tools. Exit codes: 0 success;
any other value is a failure.
3.16 terminux-package-install / -uninstall / -status (not verified)
| Synopsis | Description |
|---|---|
terminux-package-install <source_dir> [--replace] [--format text|json] |
Copies a directory containing package.yaml into ~/.terminux/packages; --replace replaces an installed package with the same id |
terminux-package-uninstall <package_id> [--format text|json] |
Removes a user package |
terminux-package-status [<package_id>] [--activate] [--format text|json] |
Shows the installed packages and what the running daemon has loaded; --activate asks the daemon to reload them (no restart) |
TERMINUX_DISABLE_USER_PACKAGES disables user packages entirely. Exit codes: 0 success; any other value is a failure.
3.17 Package development tools (--help only)
| Synopsis | Description | Exit codes |
|---|---|---|
terminux-package-new <package_id> --root <dir> [--tool <name> …] [--package-version <v>] [--dry-run] [--format text|json] |
Generates the skeleton of an after-phase package | 0 success; 2 error |
terminux-package-validate [--root <dir>] [--format text|json] |
Validates packages offline (without --root, the built-in packages); a handler must be a top-level function of its module |
0 valid; 1 invalid; 2 error |
terminux-package-test --root <dir> --package <id> [--case <name> …] [--timeout 10] [--format text|json] |
Runs the package's test cases in an isolated child process | 0 all passed; 1 a case failed; 2 error |
terminux-package-doctor --root <dir> [--run-cases] [--require-cases] [--junitxml <file>] [--timeout 10] [--format text|json] |
Combined diagnostics, optionally with JUnit XML output | 0 passed; 1 errors or failures; 2 invalid arguments |
3.18 terminux-corpus-replay
A replay tool for simulated qualification data, not a real ORFS run; do not use it for actual work. --help only.
3.19 Scripts in the source tree (not verified)
| Synopsis | Description |
|---|---|
terminux-chat <question…> |
Sends one @@ question from outside the Terminux terminal; every call is a new session; 120-second timeout. When the answer is to open the DQE Viewer, the Viewer is started locally |
terminux-lineage-graph [jobs] [--ledger <file>] [--session <S1,S2>] [--output <file>] [--no-open] |
Produces an artifact lineage graph HTML page and opens it in a browser; --session filters and colors by session |
terminux-lineage-graph trace --session <SESS> [--event-store <file>] [--output <file>] [--no-open] |
Produces the execution trace graph of one session |
terminux-dream --user-id <account> --date <yesterday|today|YYYY-MM-DD> |
Produces the work summary of a given date |
terminux-dream --user-id <account> --backfill [--days <N>] |
Catches up on the summaries of the last N days (default 1) |
terminux-build-rag-index [--source-dir <dir>] [--index-dir <dir>] [--chunk-size 512] [--chunk-overlap 64] |
Builds the RAG index from ~/.terminux/rag_knowledge (default) into ~/.terminux/rag_index (default); needs the rag extra and an embedding setup |
source terminux-llm-env.sh / source terminux-llm-env.csh |
LLM configuration templates; uncomment one backend and source the file; do not put credentials in it |
3.20 The portable bundle's install.sh and uninstall.sh
install.sh: ./install.sh [--qt-dir <dir>] [--prefix <dir>] [--no-bin-link] [--yes] [--reinstall] [--force]
| Option | Default | Description |
|---|---|---|
--qt-dir |
The existing current/qt |
The Qt SDK directory |
--prefix |
~/.local/opt/terminux |
Installation location; one subdirectory per version, current points to the version in use |
--no-bin-link |
— | Do not create terminux and terminux-qt-check in ~/.local/bin |
--yes |
— | Do not ask for confirmation |
--reinstall |
— | Reinstall the same version |
--force |
— | Skip only the "unsupported OS" block |
The installer checks SHA256SUMS first and refuses to install while a daemon is running. current is switched only after
the Qt check passes; on failure the newly created .partial is removed.
uninstall.sh: ~/.local/opt/terminux/current/uninstall.sh (--version <v> | --all) [--purge-data] [--yes]
By default ~/.terminux is kept; --purge-data deletes the data, and even with --yes you must type the full data path to
confirm. No rc file is modified; files in ~/.local/bin that were not created by this installation are never removed.
4. Terminux terminal (GUI) reference
4.1 Main window
| Area | Content |
|---|---|
| Title bar | The shell's title; when the daemon cannot be reached it shows "⚠ Terminux Core not connected (daemon not running)" and the reason |
| Status bar | At start-up "Connecting to Terminux Core…" and "Initialising session…", then "Terminux service ready" (in the interface language) |
| Menu bar | View ▸ Work Panel: show or hide the Engineering Work panel (hidden by default; not verified). Help ▸ About Terminux: version and license; Help ▸ About Qt |
| Terminal | Your shell (PTY); bash loads the hooks automatically |
| Notification Bar | At the top of the window, see 4.4 |
4.2 Terminal and shell
- The built-in bash starts with
--rcfile ~/.terminux/hooks/bash_rcfile: it first loads your~/.bashrcand then~/.terminux/bash_hooks.sh; hooks already loaded by.bashrcare not registered twice. - The GUI injects
TERMINUX_ACTIVE=1into the terminal environment, so that the tcsh rc line loads the hooks only inside Terminux. - If no hook marker (OSC 133) arrives within 10 seconds after csh or tcsh starts, a setup hint is shown once; no rc file is modified.
- Input that starts with
@@is not passed to the shell (chapter 6).
4.3 Context menu
| Item | Shortcut | Effect |
|---|---|---|
| Copy | Ctrl+Shift+C | Copy the selected text |
| Paste | Ctrl+Shift+V | Paste |
| Select All | — | Select everything |
| Clear Terminal | — | Clear the screen |
| Notification Bar ▸ Show | — | Expand the Notification Bar |
| Notification Bar ▸ Remove Oldest 10 Messages | — | Delete the 10 oldest notifications |
| Notification Bar ▸ Remove All Messages | — | Delete all notifications |
| Language ▸ 繁體中文 / English / 简体中文 | — | Language of the interface and of AI answers; stored in ~/.terminux/preferences.json |
| Open URL | — | Appears when the selected text is a URL; opens it in a browser |
| Font Size + | Ctrl+= | Larger font |
| Font Size - | Ctrl+- | Smaller font |
| Reset Font Size | Ctrl+0 | Default font size |
| Ask AI about this | — | Ask about the selected text; unavailable without a selection |
4.4 Notification Bar
| Item | Description |
|---|---|
| Notification types | Warn (warnings, for example lineage concerns), AI (AI answers and background analysis results), Gate (quality-gate results), Hint (hints) |
| Auto-collapse | Collapses to a title bar about 5 seconds after the pointer leaves; click the title bar to expand it again |
| Height | The height of the Notification Bar can be adjusted by dragging |
| Background notifications | The GUI fetches new notifications from the daemon about every 1.2 seconds; the daemon buffers at most 500 |
4.5 Work panel (not verified)
Its title is "工程工作" (Engineering Work); open it with View ▸ Work Panel. The panel's labels are in Chinese; the English column below explains each one.
| Field | Range / default | Description |
|---|---|---|
| Profile 檔 | — | Path of the Profile file; "選 Profile" (Select Profile) selects it for this session |
| Profile ID, Package | — | The Profile and package used to create the work item |
| 來源目錄 | — | Source directory (optional; limited by the Profile) |
| 工程目標 | — | Objective of the work item |
| Work ID | — | The work item to operate on |
| 授權模式 | PLAN_ONLY, PER_PROPOSAL, BOUNDED_EXPLORATION |
Authorization mode for the preview |
| 嘗試上限 | 0–100, default 1 | Attempt limit |
| Provider 上限 | 0–1000, default 5 | Provider dispatch limit |
| Tool launch 上限 | 0–100, default 2 | Tool launch limit |
| 候選寫入上限 | 0–100, default 1 | Candidate write limit |
| 補充資料 | — | Answer to a question raised by the work item |
Buttons: 選 Profile (select Profile), 建立 (create), 授權預覽 (authorization preview), 核准 (approve; asks for confirmation), 查詢 (show), 重新接管 (take over again), 暫停 (pause), 恢復 (resume), 取消 (cancel; asks for confirmation), 送出補充 (send answer). Below them the panel shows a status summary of the work item and the daemon's raw reply; "查詢" (show) never advances the work.
5. DQE Viewer reference
5.1 Common elements
| Element | Description |
|---|---|
| Workspace tabs | Temporary, Archived, Compare |
| Language menu | The header switches between English / 繁體中文 / 简体中文; the initial language follows the terminal's setting |
| Data source | The status bar shows the data source (Terminux daemon for real data; sample data is marked MOCK) |
| Refresh | Refresh reloads the data |
| Status values | Pass, Warn, Fail, Unknown |
5.2 Temporary workspace
| Section | Content and operations |
|---|---|
| Temporary jobs | Quality records of each run, grouped by job; "Search job_key / block / flow" |
| DQE items | The checks of the selected job: DQE_ID, Title, Value, Unit, Status, Date/time, Description, Reference, Source path, attachment count, executable count; filters by status and block; the header shows the total and the count per status |
| Selected item inspector | The full information of the selected item |
| Evidence / attachment preview | Preview of attachments |
| Check-in (not verified) | Check-in dry-run, Check in whole job, Confirm check-in; fields: existing target version (relative path) and workspace root. Runs through the external isvn tool |
| Temporary retention policy | A global policy for all temporary jobs: Edit policy, Save policy; retention N days |
| Temporary purge | Preview selected job purge, Preview expired jobs purge; the purge runs only after you confirm the preview |
5.3 Archived workspace (not verified)
Lists the checked-in versions; filter by phase, block and version ("Filter phase / block / version"); select a version to see its DQE items.
5.4 Compare workspace
| Section | Content |
|---|---|
| Compare sources | Choose the jobs or versions to compare (checkbox comparison not verified in 0.1.1) |
| Normalized trend | The first source is the baseline (100%); the trend of each metric is drawn and data points can be selected |
| Raw value comparison | The raw value of each source |
| Baseline delta | The difference from the baseline |
| Block filter | Filter the series by block |
| Export | Export HTML: save the comparison as HTML |
6. @@ reference
6.1 Input rules
- At the prompt of the Terminux terminal, type
@@followed by a question or a command and press Enter; the line is not passed to the shell. - Shell variables are not expanded in the text after
@@; write paths as absolute paths. - Select text, right-click and choose Ask AI about this to ask about the selected text; such input is always treated as
data and never as a
/command. - Answers appear in the Notification Bar. An LLM backend is required; the Agent is available with
openai_compatibleandgeminionly.
6.2 Keywords that do not go to the AI
| Condition | Effect |
|---|---|
Contains "dqe viewer" (or dqe_viewer, dqeviewer; case-insensitive) together with one of these verbs: open, launch, start, show, 開啟, 打開, 打开, 啟動, 启动, 顯示, 显示 |
Opens the DQE Viewer (Temporary workspace) |
Contains lineage graph, lineage dag, blood line, show lineage, 血緣圖 or 祖譜圖 |
Produces ~/.terminux/lineage_graph.html and opens it |
6.3 Local commands
Known commands that start with / are handled locally by Terminux and never sent to the LLM. Which commands are available
depends on the mode:
| Mode | Available local commands |
|---|---|
| Normal mode | All commands below except run binding. /bind-run and /unbind-run are not local commands in normal mode and are treated as ordinary questions |
| Profile mode | Only /bind-run and /unbind-run. Every other control command returns LOCAL_COMMAND_DISABLED_IN_PROFILE_MODE; nothing is run or sent |
So "bind a run, then ask" and "run an explanation or comparison with explicit commands" cannot be used with the same daemon configuration.
Run binding (Profile mode, with run_binding in the Profile)
| Command | Effect |
|---|---|
/bind-run <absolute path of the receipt> |
Binds one run to this session. The receipt must be your own formal record in the event records, with a matching content hash, and must satisfy the Profile's run_binding rules |
/unbind-run |
Removes all bindings of this session |
Plans, proposals and results
| Command | Effect |
|---|---|
/plan-only <goal> |
Produces a plan; runs nothing and creates no proposal |
/plan-propose <plan_id> <step_id> |
Creates a proposal for one step of the plan; runs nothing |
/plans, /plan <plan_id> |
List and show plans |
/use-plan <plan_id> |
Makes this plan the continuation context for later questions |
/cancel-plan <plan_id> <plan_digest> |
Cancels a plan |
/proposals |
Lists proposals |
/approve <proposal_id> <proposal_digest> |
Approves (a proposal awaiting approval expires after 10 minutes) |
/reject <proposal_id> <proposal_digest> |
Rejects |
/execute <proposal_id> <proposal_digest> |
Runs once; the arguments must equal the proposal's; cannot be repeated |
/results |
Lists execution results |
/use-result <result_id> <result_digest> |
Includes this result in later questions |
/clear-result |
Stops including a result |
/approve-plan, /execute-plan, /approve-all |
Always refused: there is no way to approve or run a whole plan at once |
Tasks (not verified)
| Command | Effect |
|---|---|
/profile <absolute path of the Profile> |
Selects a Profile for this session |
/profiles |
Lists the selected Profiles |
/task-create <profile_id> <question…> |
Creates a flow task draft |
/task-start <task_id> <task_digest> |
Approves and starts |
/task <task_id> |
Shows a task |
/task-cancel <task_id> <task_digest> |
Requests a stop |
/tasks |
Lists all your tasks in this daemon |
Engineering Work (not verified)
| Command | Effect |
|---|---|
/work-create <profile_id> <package_id> <objective> |
Creates a work item |
/work-authorize <work_id> <plan|proposal|bounded> |
Authorization preview |
/work-approve <work_id>, /work-continue <work_id> |
Approve, advance |
/work <work_id>, /works |
Show, list |
/work-answer <work_id> <answer or additional information> |
Answer |
/work-pause, /work-resume, /work-cancel, /work-takeover <work_id> |
Pause, resume, cancel, take over again |
6.4 Tools available to the AI
| Situation | Available tools |
|---|---|
Cloud backend (openai_compatible, gemini) |
Only the two execution-evidence query tools: evidence of one run, and a comparison of the evidence of 2–3 runs. Other tools are not offered to the model and return CLOUD_AGENT_CAPABILITY_DENIED when called |
| Profile mode | The Profile's tools (currently only query_orchestration_evidence) |
The AI cannot read files, run shell commands, or create actions awaiting approval by itself. Actions with side effects run only through the explicit commands in 6.3 (normal mode only).
7. Configuration reference
7.1 When settings are read, and precedence
The daemon reads its settings only at start-up; restart it after a change.
| Item | Precedence (high → low) |
|---|---|
| LLM router | ~/.terminux/llm_router.yaml (used whenever it exists) → environment variables |
| Credentials | The credentials file (TERMINUX_CREDENTIALS_FILE or ~/.terminux/credentials.json) → environment variables with the same names |
| Legacy Layer 2 settings | TERMINUX_LLM_CONFIG_PATH → ~/.terminux/config/llm_config.yaml → package template |
| STA playbook | TERMINUX_PLAYBOOK_PATH → ~/.terminux/ecc/sta_signoff_playbook.yaml |
| Quality database | TERMINUX_DQE_DB_PATH → ~/.terminux/dqe/dqe.sqlite |
| Interface language | ~/.terminux/preferences.json → TERMINUX_PREFERRED_LANGUAGE → zh-Hant |
7.2 Environment variables
"Truthy" = 1, true or yes (case-insensitive).
LLM and AI
| Variable | Default | Description |
|---|---|---|
TERMINUX_LLM_BACKEND |
Unset (AI off) | openai_compatible, gemini, llama_cpp |
TERMINUX_OPENAI_MODEL |
deepseek-chat |
Model of the OpenAI-compatible service |
TERMINUX_OPENAI_TIMEOUT_SEC |
120 | Timeout of each request (seconds) |
TERMINUX_GEMINI_MODEL |
gemini-3.6-flash |
Gemini model |
TERMINUX_LLM_MODEL_PATH |
— | GGUF file for llama_cpp |
TERMINUX_LLM_DISABLE_THINKING |
Unset | 1: turn off the thinking mode (for example Qwen3) |
TERMINUX_EMBEDDING_BACKEND |
Depends on the LLM backend | noop/none, local, gemini |
TERMINUX_EMBEDDING_MODEL_PATH |
— | Model for local embeddings |
GEMINI_API_KEY, GEMINI_EMBEDDING_MODEL |
— | Also accepted only with TERMINUX_EMBEDDING_BACKEND=gemini; the model defaults to gemini-embedding-001 |
TERMINUX_CREDENTIALS_FILE |
~/.terminux/credentials.json |
Location of the credentials file |
TERMINUX_DISABLE_CREDENTIAL_FILE |
Unset | 1: never read the credentials file |
TERMINUX_ENABLE_LINEAGE_EXPLAINER_RUNTIME |
Off | 1: ask the LLM to explain when a lineage check raises a concern |
TERMINUX_ENABLE_INTENT_FALLBACK_RUNTIME |
Off | 1: ask the LLM to parse a runfile that the fixed-format parser cannot read (sends the complete runfile) |
TERMINUX_DISABLE_RAG_BACKGROUND_REBUILD |
Unset | Truthy: do not rebuild the RAG index in the background |
TERMINUX_PREFERRED_LANGUAGE |
— | Default before a language is chosen: zh-Hant, en, zh-Hans |
Profile mode
| Variable | Description |
|---|---|
TERMINUX_AGENT_TASK_PROFILE_FILE |
The Profile file (7.5) |
TERMINUX_OUTBOUND_PAYLOAD_POLICY_FILE |
The outbound policy file (7.6) |
TERMINUX_EGRESS_AUDIT_DIGEST |
Hash mode of the outbound records (7.7) |
TERMINUX_EGRESS_AUDIT_KEYRING_FILE |
Keyring file for the keyed_persisted mode |
TERMINUX_CHAT_QUERY_REQUIRE_ORIGIN |
Off by default; when on, input from legacy clients that do not label its origin is always treated as data and / commands are not parsed (Profile mode always behaves this way) |
Paths, identity and connections
| Variable | Default | Description |
|---|---|---|
TERMINUX_HOME_DIR |
The home directory in the account database | Private base directory for sockets, the owner lock and logs; must be an absolute path that exists, is owned by you and has no group/other permissions |
TERMINUX_NODENAME |
Host name | Directory name of run/<nodename>/; ASCII letters, digits and ._- only |
TERMINUX_CORE_SOCK, TERMINUX_SOCK |
— | Isolated-deployment overrides of the Core/lineage socket (absolute paths; the parent directory must be owned by you, with no group/other permissions) |
TERMINUX_ADVERTISE_HOST |
The host's FQDN | Host name advertised in owner.json |
TERMINUX_UNIX_ONLY_IPC |
0 |
1: do not open the TCP relay ports; only 0 and 1 are accepted |
TERMINUX_GUI_BIN |
— | GUI executable |
TERMINUX_DQE_VIEWER_BIN |
dqe_viewer next to the GUI |
DQE Viewer executable |
TERMINUX_PROJECT_ID (old name TERMINUX_PROJECT) |
Unset | Declares a project |
Data locations
| Variable | Default |
|---|---|
TERMINUX_EVENT_STORE_PATH |
~/.terminux/ecc/event_store.db |
TERMINUX_ECC_STORE_PATH |
~/.terminux/ecc/ecc_store.jsonl |
TERMINUX_PLAYBOOK_PATH |
~/.terminux/ecc/sta_signoff_playbook.yaml |
TERMINUX_DQE_DB_PATH |
~/.terminux/dqe/dqe.sqlite |
TERMINUX_DQE_DEFAULT_DB_POLICY |
Unset = the default quality database may be used; deny: refuse to write to the default location unless a path is given explicitly |
TERMINUX_ORCHESTRATION_LEDGER_PATH |
~/.terminux/orchestration/ledger.sqlite |
TERMINUX_LLM_CONFIG_PATH, TERMINUX_PLUGIN_DIR |
Legacy Layer 2 configuration file; plugin directory (~/.terminux/plugins). Both must be absolute paths |
TERMINUX_AGENT_AUDIT_LOG_PATH |
~/.terminux/agent_tool_audit.jsonl |
TERMINUX_LOG_PATH, TERMINUX_PROJECT_ROOT |
Pre-exec observation log: TERMINUX_LOG_PATH → <TERMINUX_PROJECT_ROOT>/artifacts/lineage_preexec.log → ~/.terminux/lineage_preexec.log |
Switches and limits
| Variable | Default | Description |
|---|---|---|
TERMINUX_LOG_LEVEL |
ERROR |
Daemon log level: DEBUG, INFO, WARNING, ERROR, CRITICAL |
TERMINUX_AUTO_SETUP_WRAPPERS |
1 |
0: the daemon does not install hooks and wrappers at start-up |
TERMINUX_DISABLE_PACKAGES |
Unset | Truthy: stop package dispatch |
TERMINUX_DISABLE_USER_PACKAGES |
Unset | Disable user packages |
TERMINUX_DISABLE_PLUGINS |
Unset | Truthy: do not subscribe the legacy plugin pipeline |
TERMINUX_FLOW_MAX_ACTIVE_TASKS, TERMINUX_FLOW_MAX_PARALLEL_EDA, TERMINUX_FLOW_MAX_PARALLEL_PROVIDER |
1 each | Concurrency limits of tasks |
TERMINUX_EAP3_BINDINGS_FILE |
Unset | Provider bindings for Engineering Work (not verified) |
TERMINUX_FORMAL_YOSYS_EXE |
Unset | Yosys used for formal checking (not verified) |
TERMINUX_PURGE_ALLOW_USER |
The current account | Account allowed to run purge --force |
Variables set by Terminux itself, which you should not set by hand: TERMINUX_ACTIVE, TERMINUX_HOOKS_LOADED,
TERMINUX_TRACE_ROOT, TERMINUX_TRACE_SELF, TERMINUX_TRACE_PARENT, TERMINUX_TRACE_JOB, TERMINUX_TRACE_QUEUE,
TERMINUX_VENV_PYTHON.
7.3 credentials.json
{
"TERMINUX_OPENAI_API_KEY": "<key>",
"TERMINUX_OPENAI_BASE_URL": "https://api.deepseek.com",
"TERMINUX_GEMINI_API_KEY": "<key>"
}
- A JSON object; only
TERMINUX_OPENAI_API_KEY,TERMINUX_OPENAI_BASE_URLandTERMINUX_GEMINI_API_KEYare recognized, other names are ignored. - Must be a regular file (not a symlink) owned by you with permissions exactly
0600; otherwise the whole file is ignored. TERMINUX_OPENAI_BASE_URLdefaults tohttps://api.deepseek.com; a local service is for examplehttp://127.0.0.1:8080/v1.
7.4 llm_router.yaml (not verified)
When ~/.terminux/llm_router.yaml exists, the daemon uses it as the LLM router configuration and no longer builds one from
environment variables. Format:
realtime: {backend: openai_compatible, model_name: deepseek-chat, api_key: "${MY_KEY}", base_url: "https://api.deepseek.com"}
background: {backend: openai_compatible, model_name: deepseek-chat, api_key: "${MY_KEY}", base_url: "https://api.deepseek.com"}
analysis: {backend: openai_compatible, model_name: deepseek-chat, api_key: "${MY_KEY}", base_url: "https://api.deepseek.com"}
embedding: {backend: noop}
| Key | Fields |
|---|---|
realtime, background, analysis (all three required) |
backend (openai_compatible, gemini, llama_cpp, none), model_name, model_path (llama_cpp), api_key, base_url (openai_compatible) |
embedding (required) |
backend (gemini, local, noop), model_name, model_path, api_key |
${VARIABLE}in a string is expanded from the environment; unset variables are left as they are.- With this file, the router takes its keys from the
api_keyfields in the file and does not read the credentials file; avoid writing keys directly into the file. - As long as this file exists, data may be sent to the providers configured in it (see User Guide 13.2).
7.5 Profile file
Given by TERMINUX_AGENT_TASK_PROFILE_FILE. Must be a UTF-8 JSON file owned by you, with permissions 0600, no larger than
64 KiB. Anything invalid makes the whole file invalid, and every AI request that would leave the machine is refused.
| Key | Required | Type and rules |
|---|---|---|
profile_id |
Yes | Non-empty string |
tools |
Yes | Array of unique strings; may contain only query_orchestration_evidence |
context_sections |
Yes | Array of unique strings; may contain only conversation_history |
allowed_runs |
Yes | Object: keys are run ids (starting with run_, otherwise letters, digits or _), values are positive integer attempts. May be {} |
run_binding |
No | Object with four required keys (below); without it /bind-run cannot be used |
No other key is allowed.
run_binding key |
Rule |
|---|---|
max_runs_per_session |
Integer 1–8 |
require_runner |
Non-empty string without leading or trailing spaces; receipts of terminux-orfs-run have host_native |
allowed_designs |
Non-empty array of unique strings, each <platform>/<design> (each part: letters, digits, _, - only) |
max_age_sec |
Integer 1–31536000 (maximum age of the receipt's completion time, in seconds) |
In Profile mode the instructions given to the AI are fixed by Terminux and cannot be changed through the Profile file.
7.6 Outbound policy file
Given by TERMINUX_OUTBOUND_PAYLOAD_POLICY_FILE. Must be a regular file owned by you, with permissions 0600, no larger than
64 KiB.
v2 (recommended):
| Key | Rule |
|---|---|
policy_version |
terminux.egress_policy.v2 |
approval_mode |
structural_c2 (allowed by data class and limits) or exact_digest (only the listed request-content hashes are allowed) |
endpoint |
Must equal <TERMINUX_OPENAI_BASE_URL>/v1/chat/completions |
model |
Must equal TERMINUX_OPENAI_MODEL |
allowed_payload_sha256 |
Array of hashes; must be empty with structural_c2 |
approved_data_classes |
Data classes that may be sent, from: system_instructions, learner_text, conversation_history, tool_schema, tool_call, evidence_bundle, model_output, budget_summary, timing_path_evidence |
limits |
All five keys required (below) |
non_agent_egress |
Must be deny |
limits key |
Valid range |
|---|---|
learner_text_max_chars |
1–65536 |
history_max_turns |
0–200 |
history_max_chars |
0–262144 |
model_output_max_chars |
1–262144 |
requests_per_turn |
1–8 |
timing_path_evidence(per-stage timing-path data) is never sent unless listed inapproved_data_classes;evidence_bundledoes not cover it.- The old v1 shape (only the four keys
endpoint,model,allowed_payload_sha256,approved_data_classes) works only with a digest allow-list; use v2 for new configurations.
7.7 Hash modes of the outbound records
TERMINUX_EGRESS_AUDIT_DIGEST decides how each outbound record captures the integrity of the request content (the record
itself never contains the content):
| Value | Description |
|---|---|
metadata_only |
No content hash; not suitable when outbound records are required |
plain_sha |
Records the SHA-256 of the request content |
keyed_ephemeral |
HMAC with a key generated at daemon start-up and never written to disk; comparable within one daemon run, not across restarts |
keyed_persisted |
HMAC with the administrator's keyring from TERMINUX_EGRESS_AUDIT_KEYRING_FILE, plus a MAC over each whole record; verifiable after a daemon restart. If the keyring content changes, sending is refused; rotating the key requires a daemon restart |
With a structural_c2 policy, one of the last three is required. Records are kept in
~/.terminux/run/<nodename>/egress_audit/<date>.jsonl for 90 days.
7.8 STA playbook
- Template:
terminux_engine/ecc/templates/sta_signoff_playbook.yamlin the package; deploy it to~/.terminux/ecc/(see User Guide 4.5). - The top-level key is
playbook:, containingid,name,description,playbook_type,version,milestone_modelandstage_specs. - Without a playbook, stage tracking, quality gates and hints are off and nothing else is affected; the daemon log contains
TERM_ECC_PLAYBOOK_UNAVAILABLE.
7.9 preferences.json
~/.terminux/preferences.json: {"preferred_language": "zh-Hant"}, with the value zh-Hant, en or zh-Hans. Written by
the context menu's Language; read or write failures fall back to zh-Hant.
7.10 package.yaml (user packages, not verified)
package:
id: my_package # globally unique
version: 0.1.0
api: terminux.package.v1
schema: 1
when:
tools: [orfs] # dispatched after these tools finish
phases:
after: after.run # <module>.<function>; the function must be a top-level def of the module
permissions:
services: {file: read, store: write, notify: emit}
Actions can also be defined under actions: (handler, timeout_sec, description, parameters). Validate offline with
terminux-package-validate.
7.11 Hooks and wrappers installed by the daemon
| Location | Content |
|---|---|
~/.terminux/bin/ |
Wrappers for EDA tools (symlinks to _terminux_wrapper), terminux-notify, terminux-tcsh-postcmd |
~/.terminux/hooks/bash_env, bash_rcfile |
bash integration |
~/.terminux/bash_hooks.sh, ~/.terminux/tcsh_hooks.csh |
Hooks to source from an rc file |
Installation is idempotent: files with the same name that you put into ~/.terminux/bin, or symlinks pointing elsewhere,
are not overwritten, and no rc file is modified.
8. Files and data reference
8.1 ~/.terminux
~/.terminux/
├── credentials.json credentials (0600)
├── preferences.json interface language
├── llm_router.yaml optional router configuration
├── terminux.db legacy command records
├── agent_tool_audit.jsonl record of AI tool use
├── lineage_graph.html most recent lineage graph
├── lineage.<nodename>.jsonl execution records of the wrappers (lineage.jsonl in older versions)
├── lineage_preexec.log pre-exec observation log
├── ecc/ event records event_store.db, ECC snapshots, playbook, archive/
├── dqe/ quality database dqe.sqlite, retention_policy.json, scheduled_clean.log
├── lineage/ ledger.jsonl, artifact_manifests/, branch_tree.jsonl
├── orchestration/ the daemon's execution state ledger.sqlite
├── memory/ search index search_index.db
├── rag_knowledge/, rag_index/ your RAG knowledge and index
├── tools/ user_tool_catalog.yaml
├── packages/ user packages
├── plugins/ plugin directory (empty in 0.1.x)
├── bin/, hooks/, bash_hooks.sh, tcsh_hooks.csh hooks and wrappers
└── run/
├── owner.lock/owner.json the daemon's host and state
└── <nodename>/ terminux.sock, lineage.sock, daemon.log, daemon.stdout.log,
relay.pid, relay.log, egress_audit/ (Profile mode)
~/.terminux must be a directory owned by you, not writable by group or other, and not a symlink.
8.2 Execution receipt (receipt JSON)
Main fields of the JSON written by terminux-orfs-run --receipt-out:
| Field | Content |
|---|---|
schema_version |
Format version |
run_id, step_id, attempt |
Execution identity; run_id is run_ followed by 32 hexadecimal characters; step_id is orfs-<design>-<variant> |
tool_id, adapter_id, adapter_version |
Tool and adapter identity |
tool_version_evidence |
Evidence of the tool version and identity |
started_at, finished_at |
Start and end time (epoch seconds) |
process_exit_code, timed_out, termination_reason |
How the run ended |
stdout_tail, stderr_tail |
Last lines of the output |
execution_lifecycle_status, dispatch_status, evidence_status |
State of the execution, the package dispatch and evidence readiness |
output_roots |
Output root directories |
artifact_manifest_reference, artifact_manifest_id, artifact_capture_status |
Reference to the artifact manifest and the capture status |
adapter_metadata |
Includes runner (host_native), platform, design and more |
/bind-run needs this file; the same receipt must also exist in the event records with a matching content hash.
8.3 owner.json
~/.terminux/run/owner.lock/owner.json (0600): state (starting/ready), host, nodename, pid, instance_id, version,
started_at, the TCP relay's core_port, lineage_port and token (or unix_only_ipc), the result of the hook deployment,
and a start-up identity consisting only of enumerated values and hashes. token authenticates the TCP relay; do not share it.
8.4 Logs
| File | Content | Rotation |
|---|---|---|
run/<nodename>/daemon.log |
The daemon's structured messages after it acquired ownership | 10 MiB, 3 backups |
run/<nodename>/daemon.stdout.log |
Daemon output collected by terminux-launch (before ownership) |
— |
run/<nodename>/relay.log, relay.stdout.log |
Relay | 10 MiB, 3 backups |
run/<nodename>/egress_audit/<date>.jsonl |
Outbound records in Profile mode (metadata and hashes only) | Kept 90 days |
agent_tool_audit.jsonl |
Record of AI tool use | — |
dqe/scheduled_clean.log |
Scheduled DQE purge | — |
By default the daemon logs ERROR messages only, so daemon.log is empty during normal operation.
9. Quality checks (DQE) reference
9.1 ORFS checks
| Check | Description | Source | Mandatory |
|---|---|---|---|
orfs_manifest_integrity |
Identity and hash of the artifact manifest | Artifact manifest | Yes |
orfs_artifact_completeness |
The required artifacts are present and stable | Artifact manifest | Yes |
orfs_final_deliverables |
The final layout, DEF, database and netlist were produced | Artifact manifest | Yes |
orfs_process_exit_code |
Exit code of the tool process is 0 | Run result | Yes |
orfs_setup_wns |
Setup WNS ≥ 0 (ns) | 6_finish.rpt |
Yes |
orfs_setup_tns |
Setup TNS ≥ 0 | 6_finish.rpt |
No |
orfs_setup_violation_count |
Setup-violating paths = 0 | 6_finish.rpt |
Yes |
orfs_hold_violation_count |
Hold-violating paths = 0 | 6_finish.rpt |
Yes |
orfs_max_slew_violation_count |
Max-transition violations = 0 | 6_finish.rpt |
No |
orfs_max_fanout_violation_count |
Max-fanout violations = 0 | 6_finish.rpt |
No |
orfs_max_cap_violation_count |
Max-capacitance violations = 0 | 6_finish.rpt |
No |
orfs_route_drc_violation_count |
Detailed-route DRC violations = 0 | 5_route_drc.rpt |
Yes |
orfs_log_error_markers |
Error markers in the log = 0 | ORFS log (6_report.log) |
Yes |
orfs_log_warning_markers |
Warning markers in the log = 0 | ORFS log (6_report.log) |
No |
The thresholds have their signoff meaning (for example, WNS below 0 is a violation); they are not ORFS's per-design regression bounds.
9.2 Rules
- Each check results in pass, warn, fail or unknown (unreadable or undecidable).
- Overall result: any mandatory fail → fail; otherwise any warn → warn; otherwise any mandatory unknown → unknown; otherwise pass. An unknown in a non-mandatory check never turns the overall result into pass.
- A notification is sent when the overall result is warn, fail or unknown.
- The checks follow fixed rules only: no LLM, no root-cause analysis, no rerun, no design change.
9.3 Fields of a quality record
Each row in the DQE Viewer corresponds to a record in the quality database. Main fields: ProjectCode, Phase, Block, Stage,
Flow, Version, DQE_ID, VALUE, UNIT, STATUS, DATE_TIME, Reporter, PATH, attachment and executable (5 MiB each), job_key
(format YYYYMMDD_HHMMSS_NNN), and the execution identity (run id, step id, attempt). A dispatch that is sent again is not
written twice.
10. Messages and codes
10.1 Exit codes
| Command | Exit codes |
|---|---|
terminux-launch |
0 success; 1 failure |
terminux-daemon |
0 normal stop; 2 socket paths cannot be resolved; 3 start-up failed; 4 an owner or a legacy daemon exists |
terminux-doctor |
0 ready; 1 attention |
terminux-qt-check |
0 passed; 1 failed |
terminux-orfs-run |
0, 1, 2, 3, 5, 130, 143 (3.8) |
terminux-orfs-report |
0 success; 2 error |
python -m terminux_engine purge |
0 success; 1 --force refused; 2 invalid arguments; 5 owner on another host |
dqe-scheduled-clean |
0 success; 1 failure; 2 invalid arguments; 3 completed with a degraded policy; 5 owner on another host |
terminux-cold-backup |
0 success; 2 a precondition is not met |
terminux-rollback-check |
0 compatible; 2 incompatible or unreadable; 5 owner on another host |
terminux-work, terminux-package-new |
0 success; 2 error |
terminux-package-validate |
0 valid; 1 invalid; 2 error |
terminux-package-test |
0 all passed; 1 a case failed; 2 error |
terminux-package-doctor |
0 passed; 1 errors or failures; 2 invalid arguments |
10.2 Daemon and launcher codes
| Code | Where | Meaning and what to do |
|---|---|---|
TERM_DAEMON_OWNER_EXISTS |
Daemon stderr (exit 4) | Another daemon holds the owner lock (possibly on another host). Use or stop it on its host; use terminux-launch --reset only after confirming that it no longer exists |
TERM_LEGACY_DAEMON_RUNNING |
Daemon stderr (exit 4) | A legacy daemon still runs on the old path ~/.terminux/terminux.sock; stop it first |
TERM_AGENT_SOCKET_UNAVAILABLE |
Daemon (exit 2) | The socket path cannot be used; the message includes one of the detailed codes below, the UID and the expected path |
TERM_RUNTIME_DIR_MISSING, _NOT_A_DIRECTORY, _IS_SYMLINK, _WRONG_OWNER, _TOO_PERMISSIVE, _UNAVAILABLE |
Same | ~/.terminux does not exist, is not a directory, is a symlink, is not owned by you, is writable by group/other, or cannot be used. Fix the permissions or the path; Terminux never deletes existing files on its own |
TERM_HOME_DIR_UNRESOLVED, TERM_HOME_DIR_UNAVAILABLE |
Same | The home directory cannot be found in the account database, or cannot be used |
TERM_AGENT_SOCKET_PATH_OCCUPIED |
Same | A regular file, directory or symlink occupies the socket path |
TERM_SOCKET_PATH_TOO_LONG |
Same | The socket path is too long (the Unix socket limit is about 107 bytes); shorten TERMINUX_HOME_DIR or the override path |
TERM_AGENT_SOCKET_OVERRIDE_INVALID |
Same | The value of TERMINUX_CORE_SOCK, TERMINUX_SOCK or TERMINUX_HOME_DIR is invalid |
TERM_AGENT_SOCKET_LEGACY_PATH_REJECTED |
Same | The override value is the retired /tmp/terminux.sock or /run/user/<uid>/terminux/terminux.sock |
TERM_LEGACY_SOCKET_OVERRIDE_IGNORED |
daemon.log (WARNING) |
The override value equals the old default path; it was ignored and the current rules were used |
TERM_NODENAME_INVALID |
Daemon, CLIs | TERMINUX_NODENAME contains characters that are not allowed |
TERM_UNIX_ONLY_IPC_INVALID |
Daemon | TERMINUX_UNIX_ONLY_IPC is neither 0 nor 1 |
TERM_SERVICE_START_FAILED |
Daemon (exit 3) | Start-up failed; restart with TERMINUX_LOG_LEVEL=INFO and read daemon.log |
TERM_SOCKET_BIND_FAILED, TERM_LINEAGE_LISTENER_NOT_STARTED, TERM_SOCKET_CONFLICT_HINT |
daemon.log |
The lineage socket could not be created; the AI and background analysis do not start. If you can connect to it, someone is using it, so do not delete it; remove it by hand only after confirming that it is a leftover |
TERM_DAEMON_OWNER_LOCK_RETAINED |
daemon.log |
At shutdown the daemon could not confirm that the data was closed cleanly, and keeps the owner lock on purpose |
TERM_EVENT_STORE_UNAVAILABLE |
daemon.log |
The event records cannot be opened or written; package dispatch and event recording stop. Fix ~/.terminux/ecc and restart |
TERM_ECC_PLAYBOOK_UNAVAILABLE |
daemon.log |
No STA playbook (an optional feature); nothing else is affected |
TERM_EGRESS_AUDIT_UNAVAILABLE |
daemon.log |
The outbound-record directory of Profile mode cannot be used; sending is refused |
TERM_DATABASE_REMOTE_OWNER |
Commands that open the database directly (exit 5) | The daemon runs on another host; run the command there |
TERM_DAEMON_OWNER_UNAVAILABLE |
terminux-launch, relay |
The owner state is not ready, cannot be read, or cannot be reached over TCP |
TERM_DAEMON_OWNER_UNCONTAINED |
terminux-launch |
You are in Profile mode but the existing daemon was not started in Profile mode; stop it and restart with the Profile settings |
TERM_DAEMON_OWNER_IDENTITY_MISMATCH |
terminux-launch |
The Profile/policy loaded by the existing daemon differs from yours (Learner build) |
TERM_LAUNCH_DAEMON_NOT_READY |
terminux-launch |
Still not ready after 30 seconds; the hooks may not be deployed yet |
TERM_LAUNCH_WRAPPER_SETUP |
terminux-launch |
The hook deployment failed or is disabled; read daemon.log as the message says |
TERM_LAUNCH_GUI_NOT_FOUND |
terminux-launch |
The GUI executable cannot be found |
TERM_LAUNCH_RELAY_START_FAILED, TERM_LAUNCH_RELAY_START_TIMEOUT, TERM_LAUNCH_RELAY_STOP_TIMEOUT |
terminux-launch |
The relay failed to start, timed out, or stopping the old relay timed out |
TERM_LAUNCH_OWNER_DIRECTORY_UNSAFE |
terminux-launch --reset |
The owner lock is not a directory owned by you; deletion is refused |
TERM_LAUNCH_FAILED |
terminux-launch |
Other failures; the reason follows |
10.3 terminux-orfs-run codes
| Code | Meaning |
|---|---|
NATIVE_RUN_AS_ROOT_REFUSED |
Running as root (exit 2) |
NATIVE_SETUP_INVALID |
The env script or make cannot be found, or another execution setting is invalid (exit 2) |
DOCKER_EXECUTION_REMOVED |
The removed --docker-image was used (exit 2) |
LEDGER_SHARED_WITH_DAEMON |
--ledger-db points to the daemon's ledger (exit 2) |
EXECUTION_RECEIPT_NOT_DURABLE |
The run succeeded but the receipt was not written into the event records (exit 3) |
PACKAGE_RECORD_STORE_UNAVAILABLE |
The event records cannot be opened or written, so the package records (including the timing-path evidence) cannot be stored; the meaning of the exit code is unchanged |
EXECUTION_INTERRUPTED, EXECUTION_INTERRUPTED_BEFORE_START |
A signal arrived during the run or before it started |
EXECUTION_CLEANUP_UNCONFIRMED |
It could not be confirmed that the flow's process group ended, so no receipt is written |
EXECUTION_FINALIZATION_INTERRUPTED, SIGNAL_DURING_FINALIZATION, SIGNAL_AFTER_PERSISTENCE |
A signal arrived during finalization or after the receipt was written; a signal that arrives after the receipt is complete does not change the exit code |
TERMINUX_DESIGN_NICKNAME_MISMATCH |
--design differs from the design name resolved by ORFS; the flow stops before it starts |
TERMINUX_FORBIDDEN_ENV |
The environment or the env script sets a variable that is not allowed: MAKEFLAGS, GNUMAKEFLAGS, MAKEOVERRIDES, MAKEFILES, DESIGN_CONFIG, FLOW_VARIANT, WORK_HOME, IN_NIX_SHELL, and OPENROAD_EXE/YOSYS_EXE unless given with --openroad-exe/--yosys-exe. These values may come only from the arguments assembled by Terminux |
TERMINUX_NATIVE_TOOL_MISSING, TERMINUX_NATIVE_TOOL_DIGEST_MISMATCH, TERMINUX_NATIVE_TOOL_REALPATH_CHANGED |
A declared tool does not exist, or the content or real path of a tool file changed during the run |
10.4 Codes in @@ answers
| Code | Meaning |
|---|---|
RUN_BOUND |
Bound (or already bound) |
RUN_UNBOUND |
Bindings removed |
RUN_NOT_BOUND |
No run is bound to this session |
RUN_BIND_DISABLED |
No valid session, or the Profile has no run_binding |
RUN_BIND_USAGE |
Wrong syntax (/bind-run needs one absolute path; /unbind-run takes no arguments) |
RUN_BIND_UNSUPPORTED |
Unsupported argument (for example last); give the absolute path of the receipt |
RUN_BIND_RECEIPT_UNREADABLE |
The receipt path is not absolute, cannot be read, or is not a regular file |
RUN_BIND_RECEIPT_INVALID |
The receipt is not valid JSON, or lacks run_id, attempt or adapter_metadata |
RUN_BIND_NOT_PROJECTED |
The event records contain no formal receipt for this run |
RUN_BIND_FOREIGN_OR_UNTRUSTED |
The same run has records not written by you, or a record's content hash does not match |
RUN_BIND_ATTEMPT_MISMATCH |
The event records have no such attempt |
RUN_BIND_AMBIGUOUS |
The same run/attempt matches several records |
RUN_BIND_OUTSIDE_POLICY |
The runner, <platform>/<design> or receipt time does not satisfy the Profile's run_binding |
RUN_BIND_LIMIT |
max_runs_per_session reached |
RUN_BIND_AUTHORITY_UNAVAILABLE |
The event records cannot be used |
RUN_BIND_POLICY_UNAVAILABLE |
The outbound policy cannot be read; binding is refused |
TASK_POLICY_INVALID |
The Profile file is invalid (format, permissions, size); every AI request that would leave the machine is refused |
PROFILE_PROVIDER_UNSUPPORTED |
Profile mode supports the openai_compatible backend only; no request was sent |
LOCAL_COMMAND_DISABLED_IN_PROFILE_MODE |
In Profile mode only /bind-run and /unbind-run are available; nothing was run or sent |
CLOUD_AGENT_CAPABILITY_DENIED |
With a cloud backend, the AI tried to use a tool that is not allowed |
PLAN_BATCH_CONTROL_NOT_SUPPORTED |
/approve-plan, /execute-plan or /approve-all was used |
PROPOSAL_PENDING_LIMIT_EXCEEDED |
This session already has the maximum number of proposals awaiting approval (16) |
10.5 Task codes (not verified)
| Code | Meaning |
|---|---|
TASK_NOT_FOUND_OR_OUT_OF_SCOPE |
The task does not exist or is outside your scope (deliberately not distinguished) |
TASK_DIGEST_MISMATCH |
task_digest does not match the draft |
TASK_ORIGIN_SESSION_REQUIRED |
Only the session that created the task can start it |
TASK_INSTANCE_EXPIRED |
Not a task of the current daemon (history from before a restart); read-only |
TASK_BUSY |
The slots are taken by other tasks; no authorization was consumed |
TASK_WORKER_UNCONFIRMED |
The previous action has not been confirmed as finished, so its slot cannot be reused |
TASK_ALREADY_STARTED |
The same task cannot be started twice |
TASK_REVALIDATION_FAILED |
Revalidation at start did not match |
TASK_RUN_ACCESS_UNVERIFIABLE |
It cannot be proven that you may access the given run |
TASK_PROPOSAL_CONTROL_DENIED |
Proposals inside a task cannot be operated with the single-proposal commands |
TASK_BUDGET_EXHAUSTED, TASK_DEADLINE_EXCEEDED |
Budget or deadline used up; no more work is dispatched |
TASK_EVIDENCE_INVALID |
Records, scope or hashes are inconsistent or missing |
TASK_OUTCOME_UNCONFIRMED |
It is unknown whether an action completed; it is never resent automatically |
TASK_INPUT_INVALID |
Invalid input at creation |
TASK_PROVIDER_UNAVAILABLE |
The LLM provider needed for analysis is unavailable (showing and cancelling still work) |
LEGACY_DOCKER_EXECUTION_DISABLED, LEGACY_HOST_RUNNER_EXECUTION_DISABLED |
Old execution modes are disabled; historical tasks can still be read |
11. Limits, timeouts and defaults
| Item | Value |
|---|---|
terminux-launch waiting for the daemon |
30 seconds |
| GUI reconnecting to the daemon | Every 3 seconds |
| GUI fetching background notifications | About every 1.2 seconds; 1.5-second timeout each |
| Daemon notification buffer | 500 notifications |
| Notification Bar auto-collapse | About 5 seconds after the pointer leaves |
| Lineage check (GUI wait) | 30 seconds |
Hook notifying the daemon (terminux-notify) |
2 seconds; silently skipped when the daemon is not running |
| csh/tcsh hook setup hint | When no marker arrives within 10 seconds after start-up |
terminux-chat |
120 seconds; 5 seconds to open the session |
| OpenAI-compatible request | 120 seconds (TERMINUX_OPENAI_TIMEOUT_SEC) |
terminux-orfs-run |
900 seconds (--timeout-seconds) |
Explaining one run (explain_run) |
300 seconds |
| Proposals awaiting approval | Expire after 10 minutes; at most 16 per session |
| Execution results | Kept 30 minutes (in memory only) |
| Run bindings | 1–8 per session (Profile setting); cleared when the daemon restarts |
| Concurrent tasks | Each limit defaults to 1 |
| Profile and outbound policy file size | 64 KiB |
| Daemon/relay log | Rotated at 10 MiB, 3 backups |
| Wrapper execution records | gzip backup above 10 MiB, 3 backups; checked every 300 seconds |
| Outbound records | Kept 90 days |
| Attachment and executable in a quality record | 5 MiB each |
| DQE Viewer retention setting | 1–3650 days |
| Single message on the Core socket | 1 MiB |
| Default timeout of package tests | 10 seconds |
terminux-work authorize defaults |
attempts 2, provider dispatches 12, tool launches 5, candidate materializations 2 |
12. Glossary
| Term | Description |
|---|---|
| Attempt | The number of an attempt within one run |
| Artifact manifest | A mechanical record of a run's output files (path, size, SHA-256); immutable once written |
| Baseline | The run used as the reference in a comparison |
| Cloud backend | openai_compatible or gemini; with it the AI can only query evidence |
| Daemon | The background service, one per Linux account |
| DQE | Design Quality Evidence: quality verdicts produced by fixed rules |
| Engineering Work | Multi-round engineering work under an overall budget (not verified) |
| Event records | ~/.terminux/ecc/event_store.db; every formal record is only ever appended |
| Flow task | A bounded task with fixed steps: baseline → explanation → one change → candidate → comparison (not verified) |
| Host-native | Tools run directly on the host under the user's account |
| Job / job_key | A group of quality records of one run in DQE; job_key has the format YYYYMMDD_HHMMSS_NNN |
| Lineage | Data lineage: which inputs a step actually read and which outputs it wrote |
| Normal mode | Operation without a Profile; all local commands except run binding are available |
| Owner | The daemon that holds the owner lock and is serving |
| Package | An extension unit: package.yaml plus Python code |
| Profile mode | A mode in which the administrator restricts the AI's scope and the data sent out; any invalid setting means refusal |
| Proposal | An action with side effects awaiting approval; run once after approval |
| Receipt | The formal result record of one tool execution |
| Relay | Local relay on a host that is not the owner |
| Session | The identity a GUI or CLI gets when it connects to the daemon; it ends when the connection closes |
| Temporary / Archived | DQE records not yet checked in / versions checked in through isvn |