Protocol reference
The contract between a host plugin (napari, Fiji, QuPath) and an app's tools: the schema a host reads, the registry where it finds apps, and the messages it exchanges with the worker. This is protocol version 1. Every field marked additive below was added within version 1: a host that does not know it can ignore it. A change that is not additive would be protocol 2.
Schema (what hosts read)
<registry>/<name>.schema.json, generated by labconstrictor-tools describe without running any tool:
{ "protocol": 1, "application": str, "version": str, "tools_version"?: str, "features"?: [str],
"tools": [ { "id", "label", "description"?,
"inputs": [ { "name", "label", "type", "required", "default"?, "description"?, "choices"?,
"minimum"?, "maximum"?, "unit"?, "axes"?, "pixel_size_of"?, "nullable"?, "group"?, "advanced"?, "enabled_when"?, "group_collapsed"?, "clear_after_run"?, "choices_from"?, "pick_channel"? } ],
"outputs": [ { "name", "type", "axes"?, "display"?: {"apply_to", "relative_to"?}, "replace"? } ] } ] }
A host must skip, and report, a schema whose protocol it does not support.
Input type: string integer float boolean choice image labels table file folder. Output type: image labels table values affine file message points shapes.
Inputs
description: optional but recommended; the input's help, which hosts show on hover with an ⓘ after the label.checkandtestwarn when it is missing.nullable: true(additive): the parameter is optional and has no default (= NoneorOptional[...]). A host lets the person leave it unset and then omits it from the request; the tool receivesNone. Showing 0 or an empty string instead is a bug.folder: a directory path; the worker checks that it exists. Hosts show a folder chooser.axes(an input, or an image/labels output): a string of distinct labels fromT C Z Y X S, one per array dimension. Anything else is aDeclarationError.
Presentation and interaction hints (all additive). A host that ignores them shows a plain form, so a tool must accept every parameter whether or not it is "enabled":
group: a heading, shown where the group first appears.advanced: true: listed under a collapsed "Advanced settings".group_collapsed: true(withgroup): the group is an accordion section that starts folded.enabled_when: {"param", "equals"?}: the parameter applies only whenparamis set or true, or equals one of the listed values.clear_after_run: true: after a successful run, a host that keeps form values between runs puts the parameter back to its default (or unset).choices_from: {"tool", "depends", "field"}(string parameters): the host runstoolwith the current values of the parameters named independs, reads the list underfieldof itsvaluesresult and shows a dropdown. When the call cannot be answered it falls back to a text field. The value stays a free string for the tool. A host that builds its form before the person types anything (Fiji) asks with the values of the previous run of the same app, kept in<LC_HOME>/state, and shows the text field the first time.pick_channel: true(image inputs whoseaxesareYXor absent): the host lets the person choose a channel of the chosen image (by name where the host has names, by number otherwise) and sends only that channel, as a 2D image. A host that cannot list channels sends the image as it is.- output
replace: true(image, labels, table, affine overlay): a new run replaces the previous result of the same output (same layer or window name) instead of adding "name [1]".
Value rules (enforced by the worker)
Each violation is a FAILURE with code invalid_parameter, unless another code is named, or a DeclarationError when the app is registered.
booleanmust be JSONtrueorfalse, never text or a number. Achoicevalue must match a choice in type and value. Afloatis never a boolean.integerandfloatmust be JSON numbers. Text (even"3"), lists, objects, NaN and infinity are refused:'N' must be an integer, got text,'N' must be a number, got a list,'N' must be a finite number. An integer-valued float such as3.0is accepted for aninteger. A number beyond the float range is refused for afloat.file,folder,imageandlabelsvalues must be text paths:'N' must be a path (text), got a list: the host must send the file or folder path as text. An image may also be a shared-memory descriptor (see Shared-memory images).nullmeans "not given": the parameter takes its default or, whennullable, the tool receivesNone.Optional[...]with a default other thanNoneis refused at registration.- A default must be valid for its declared type (checked when the schema is generated).
- A
choicedeclared with anEnumreaches the tool as the Enum member. - An image or labels input with no pixels is refused with
empty_image. - A table input is a UTF-8 CSV file with a header line. The tool gets a DataFrame exactly as written: floats keep every digit (
float_precision="round_trip"); column names stay as written, duplicates and empty names included (address those by position); an empty cell is missing;NaN,nanandNANare missing numbers, but a text column keeps them as text; the other words pandas calls missing (NA,None,null, ...) stay text, except in a column whose other cells are all numbers. A missing file isfile_not_found; an empty file or one that is not a UTF-8 CSV isunreadable_table. - Integers of any size and floats up to the double range are carried. A value beyond a declared
Min/Max(or the notebook form's ±(2**53 - 1),notebook.MAX_FORM_INTEGER) is refused, never clamped, with the sentence every host uses:'L' must be <= 9007199254740991or'L' must be >= -9007199254740991.
Results and what the tool must return
A tool returns one value, or a tuple with one value per declared output (tool returned N values, declared M). A value that does not match its declaration fails the task with bad_return: the <type> output '<name>' must be <what>, got <what arrived>. The expected values are an array of numbers (image, labels), a DataFrame, dict of lists or list of dicts (table, points), a dict (values), a path (file), text (message) and a finite 3x3 matrix of numbers (affine).
Output names are file names (<name>.tif, .csv, .geojson in the result folder), so Name(...) must be one portable file name: no /, \, :, <>"|?*, control characters or NUL, not . or .., no leading space or trailing space or dot, and not a Windows device name (CON, NUL, COM1, ...). Anything else is a DeclarationError; the writers also refuse (bad_return) a path that would leave the result folder.
Images and labels
- An empty array is
bad_return(image is empty (shape ...)). Complex, object, text and bytes arrays areunsupported_dtype. - Integer values never change. Wide integers that fit 16 bits are stored as 16-bit; others must be exact as float32, otherwise
unsupported_dtype(for example a uint64 of 2**64-1). Floats are stored as float32 (about 7 significant digits); values outside the float32 range fail. - A declared
axesis a promise: an array with another number of dimensions isbad_returnand nothing is written. Withoutaxes, the host getsYX,ZYXorCZYXfor 2, 3 or 4 dimensions, and noaxesotherwise. - A tool whose output axes depend on the input returns
WithAxes(array, "TZYX"); a declaredaxesmust agree, otherwisebad_return. The result'saxesare the returned ones. - Hyperstacks (feature
result_axes_v1): a result with known axes (declared or returned) that are a subsequence ofT Z C Y Xending inY X, more than two dimensions and none of size 1, a pixel type ImageJ stores (uint8, uint16, int16, float32) and less than 4 GiB is written as an ImageJ hyperstack TIFF, which Fiji opens with its dimensions. The array is never reordered. Any other result is a plain TIFF.
Tables and points. Written as UTF-8 CSV. Line breaks, quotes and commas in cells and names are quoted and arrive unchanged. A NUL character in a column name or cell is refused with bad_return (the table output 'X' has a NUL character in a cell of column 'c': remove it); a lone surrogate or other text that is not UTF-8 is refused with bad_return (... cannot be written as a UTF-8 CSV ...). A points result is {path, n, columns, apply_to?}: a CSV whose first two columns are y and x, finite pixel coordinates in the frame of the image named by apply_to (else of the first image); other columns are properties of each point.
Shapes. {path, n, apply_to?}: a GeoJSON FeatureCollection file of Polygon and MultiPolygon features, [x, y] coordinates in the same frame, pixel centres at integers. Feature properties are kept; a label property links an outline to its label. A GeoJSON dict returned by a tool is checked before anything is written: a Polygon is a list of rings (outer boundary first, then holes), a MultiPolygon a non-empty list of polygons, every ring at least 4 [x, y] positions of two finite numbers, closed, with at least 3 distinct vertices. Anything else is bad_return naming the feature, polygon and ring. An empty result is a FeatureCollection with no features. A host that does not know shapes lists the file.
Message. {text}: short plain text.
Tools version and features
Two additive fields say what produced a schema:
tools_version: thelabconstrictor-toolsversion that randescribein the app's interpreter (labconstrictor_tools.__version__, for example0.3.0a1for tagv0.3.0-alpha.1; see OPERATIONS.md).features: the sorted list of feature ids (labconstrictor_tools.features.FEATURES). An id means "this Tools implements that rule". It is added in the change that implements it and is never renamed or reused.
register copies both into the registry entry; describe and doctor print them. A missing field means unknown/old.
| Id | Meaning | Since |
|---|---|---|
reserved_inputs_v1 |
the worker accepts and ignores reserved underscore inputs it does not know (Reserved inputs) | 0.2.0rc1 |
retention_prune |
the command labconstrictor-tools prune [--root results\|runs\|all] [--dry-run] [--json] and labconstrictor_tools.retention exist; only folders with a valid .lc-owner.json and .lc-done.json are removed (Result folders and run records) |
0.2.0rc1 |
shm_order_v1 |
a shared-memory descriptor's order is honoured (Shared-memory images). A host that sends F blocks requires it |
0.3.0a1; the one id added after its behaviour: older versions behave the same but cannot be told apart |
app_hosts_v1 |
register records the app's hosts, and a host lists an app only if it is named there (App hosts) |
0.3.0a1 |
host_requirements_v1 |
register --app-manifest records the app's host_requirements, and host_requirements.check gives every host the same verdict (Host requirements) |
0.3.0a2 |
result_axes_v1 |
a result with known axes in ImageJ order is written as an ImageJ hyperstack TIFF (Images and labels). Hosts need nothing new | 0.3.0a4 |
Some behaviour has a version but no id. Tools >= 0.3.0a1 maps big TIFF files (see TIFF files); a host can observe it only as speed, memory use and the Windows file lock. The run-record helpers of the runs module also need 0.3.0a1.
Compatibility rules for hosts
A host that needs a minimum states it as (min_tools_version, required_features) and applies these rules to every schema it loads, with labconstrictor_tools.compat.check_schema (Python hosts) or the same rules in its own language (Fiji and QuPath read the cases from conformance.json, section compat; see CONFORMANCE.md). The result is ok, warn or refuse, with one sentence for the person:
protocolnot supported:refuse.- A required feature missing from
features, or nofeatureslist:refuse, "needs; update the app's labconstrictor-tools". tools_versionmissing (unknown/old):refusewhen a minimum is set, otherwisewarn, "Tools version unknown".tools_versionbelow the minimum:refuse. Below the optionalwarn_belowbut not below the minimum:warn.- Otherwise
ok. Atools_versionthe host cannot parse iswarn, never a crash. - A host that starts
pruneafter a run requiresretention_prune, or checks for it before starting the subprocess. Without it the host starts nothing and never deletes a folder itself. - A host that applies the per-host listing rule requires
app_hosts_v1(withmin_tools_version0.3.0a1). An app whose Tools lacks it is refused by rule 2 with "lacks app_hosts_v1: update it" (conformance.json,app_hosts.compat_cases).
Versions compare as PEP 440: 0.2.0a1 < 0.2.0b1 < 0.2.0rc1 < 0.2.0 < 0.2.1, and 0.2.0rc1 < 0.3.0a1 < 0.3.0. Tags v0.2.0-rc.1 and v0.2.0-rc.2 both report 0.2.0rc1 with different code, so a host that needs anything from 0.3.0a1 sets that as its minimum.
App hosts (which host lists an app)
An app declares which hosts may list it, and a host never lists an app whose declaration excludes it. Feature id app_hosts_v1; reference: labconstrictor_tools.app_hosts.listed_for; test vectors: conformance.json, section app_hosts.
Where the declaration comes from. The hosts: line of the app's labconstrictor-app.yaml (Tool markers), which the installer passes to register --app-manifest <file>; --hosts notebook,napari is the command-line equivalent (the two are exclusive). The reader accepts a quoted key, a flow or block list and a UTF-8 byte order mark; a form it does not understand is refused, never read as absent. register validates the list and writes it into the registry entry as hosts. A manifest with no hosts key still registers, and register prints the "declares no hosts" sentence below on stderr.
The rule. For each registered app, a host calls listed_for(entry, "<its own name>") (napari, fiji or qupath; Fiji and QuPath implement the same rule) and acts on (listed, sentence):
Entry hosts |
listed | sentence (exact; {app} is the entry's name, the list is written as declared, separated by ,) |
|---|---|---|
| contains the host | yes | none |
| valid, does not contain the host | no | '{app}' is not listed in {host}: the app declares hosts: {hosts} |
| absent (older installers) | yes, in every host | '{app}' declares no hosts, so it is listed in every host; register it with --app-manifest (or --hosts) to choose |
| present but not valid: not a list, empty, a non-text item, an unknown or repeated name, a name in capitals | no, in no host | '{app}' is not listed in {host}: its hosts declaration is not valid ({problem}); register the app again with a valid one |
The problems are: hosts must be a list of host names, hosts is empty; write at least notebook, hosts must contain only text, unknown host name 'x' (known: notebook, napari, fiji, qupath), host name 'x' appears twice. The manifest reader and --hosts also refuse hosts has an empty item (a trailing or doubled comma, or a bare '-'). An unknown name for the asking host is a bug in the host: listed_for raises ValueError.
A host writes every non-empty sentence to the Tools log, the absent case included, and shows the skip sentence wherever it reports apps it leaves out.
What is not filtered. The command line (labconstrictor-tools list|run|check|test), notebooks (%%lc_tool, run_once) and the worker. labconstrictor-tools list prints each app's declaration (hosts: notebook, fiji, not declared (listed in every host) or INVALID (...)); list --json adds "hosts": {app: [...] | null} (null: not declared, or not a list) and "hosts_status": {app: "declared" | "absent" | "invalid"}. An app that declares only notebook is registered, usable from the command line and hidden from all three hosts.
Host requirements (which plugin an app needs)
The compatibility rules let a host require a minimum Tools in the app. This is the other direction: an app says which host plugin it needs, so that a person with an old plugin is told to update. Feature id host_requirements_v1; reference: labconstrictor_tools.host_requirements.check; test vectors: conformance.json, section host_requirements.
Where the declaration comes from. The app's labconstrictor-app.yaml (Tool markers):
host_requirements:
qupath:
min_version: 0.1.0-alpha.6 # a release tag of the plugin, with or without "v"
features: [shapes_owner_v1] # optional: host feature ids (HOST_FEATURES.md)
why: Replace keeps your own annotations # optional, one line
required: false # optional; true refuses instead of warning
register --app-manifest validates the block and copies it into the registry entry; an invalid block is refused and nothing is registered. Only napari, fiji and qupath can be named. The reader understands this block form only (two levels of key: value, a flow list on one line, quoted or plain text, true/false).
The rule. For each registered app, a host calls check(entry, "<its own name>", <its own version or None>, <its own feature ids>) and acts on (status, sentence):
| Situation | status | sentence (exact; {app} is the entry's display_name, {why} is (<why>) or empty, {url} is https://github.com/CellMigrationLab/LabConstrictor-{plugin}/releases/latest) |
|---|---|---|
| nothing declared for this host, or new enough with every feature | ok |
none |
the host's version is below min_version |
warn (refuse with required: true) |
{app} needs LabConstrictor-{plugin} {min_version} or newer{why}; this is {host_version}. Update the plugin: {url} |
| a required host feature is missing | warn (refuse with required: true) |
{app} needs LabConstrictor-{plugin} with {features}{why}; this plugin does not have it. Update the plugin: {url} |
the host's version is unknown or unreadable (Fiji's loose script) while min_version is set |
always warn |
{app} needs LabConstrictor-{plugin} {min_version} or newer{why}; the version of this plugin is unknown. Update the plugin if the app misbehaves: {url} |
| the declaration is not valid (hand-edited entry) | warn |
{app} has a host_requirements declaration that is not valid ({problem}); register the app again with a valid one |
{plugin} is napari, Fiji or QuPath. Versions compare as PEP 440 after dropping a leading v (v0.1.0-alpha.6 = 0.1.0a6; 0.1.0a6.dev0 < 0.1.0a6 < 0.1.0rc1 < 0.1.0); version_order in the vectors pins the order. An unknown asking host raises an exception.
What a host does. ok: nothing. warn: the app stays listed; the sentence is shown where the person picks the app (a status line, a tooltip or one dialog per session) and written to the Tools log. refuse: the app's tools do not start. napari keeps the app listed and refuses Run with the sentence; Fiji and QuPath leave the app out of their list and show the sentence where they report skipped apps. A host without host_requirements_v1 ignores the field. The command line and notebooks are never checked.
Each host's version source and feature ids are in HOST_FEATURES.md.
Result folders and run records (retention)
Under <LC_HOME>, results/<YYYYMMDDTHHMMSS>_<6 hex>_<app>_<tool> holds the files of a run and runs/<time>_<app>_<tool> its record (run.json). Feature retention_prune. The reasons behind the policy are in SPEC_WRONG_SCIENCE.md.
- Markers. Whoever creates the folder (a host, the CLI,
runs.record) writes.lc-owner.jsonfirst:{"lc_marker": 1, "kind": "result|run", "name": "<folder name>", "host": "cli|napari|fiji|qupath|notebook", "pid": n, "created": "<UTC ISO-8601 with Z>", "token": "<uuid4>"}. It writes.lc-done.jsonlast, atomically (temporary file, then rename):{"finished": "<UTC ISO-8601>", "status": "ok|failed|cancelled"}.labconstrictor_tools.retention.write_ownerandwrite_doneare the reference writers. - Hosts never delete anything under
results/orruns/. After writing the done marker, a host startslabconstrictor-tools prunein a subprocess and ignores its exit code. - What
pruneremoves: the oldest eligible folders beyond the newest 20 (results) or 50 (runs). Eligible means: a real directory (not a symlink, junction or other reparse point), a direct child of the root, a name made ofA-Za-z0-9_.-, a valid owner marker whosenameis the folder's name and whosekindmatches the root, and a done marker. Other folders (foreign, without markers, unfinished or crashed), links and files are never touched and do not count. Order: the marker'screated, then the name. - How:
prunetakes a non-blocking lock on<LC_HOME>/.retention.lock; if it cannot, it exits 0 and deletes nothing. A folder is renamed to.lc-deleting-<token>inside the root, then removed without following links; the nextprunefinishes an interrupted removal.--dry-runlists what a real run would remove and changes nothing. Exit code 0, also when the lock is held; 1 when a folder could not be removed (the report says which and why).--outfolders,state,logsand everything outside the two roots are never touched.
A Python host that writes its own run record (napari). runs.record is for the CLI and the Python client: it creates the folder when the run is over, writes the markers and run.json, and prunes. A host instead creates its folder when the run starts (owner marker first, so a crash leaves an owned, unfinished folder that nobody removes) and never prunes. It uses three functions that create, delete and prune nothing:
runs.build_record(app, tool_id, inputs, task, seconds, stderr="", *, run_id=None, started_utc=None, finished_utc=None) -> dict: the content ofrun.json, the same dictruns.recordwrites. The host-owned_job_dirandmatrix_yxare left out, the stderr tail is cut toruns.STDERR_TAIL_CHARS, andfinished_utcdefaults to now. Withrun_idandstarted_utcthe record carries them (run_idfirst,started_utcaftertool); without them it has neither key, as the CLI writes it.runs.record_json(content) -> str: the text ofrun.json(indented; anything that is not JSON is written as text).runs.done_status(task_status, cancel_requested=False) -> str: the status for.lc-done.json.COMPLETEisok,CANCELEDiscancelled,FAILEDisfailed, andCRASHEDiscancelledwhen the person pressed Cancel (Task.cancel_requested),failedotherwise.
The host writes the owner marker with retention.write_owner(folder, "run", "<host>"), run.json with the text above and the done marker with retention.write_done(folder, runs.done_status(...)), then starts labconstrictor-tools prune (compatibility rule 6). The three functions arrive in 0.3.0a1: a host that calls them requires min_tools_version 0.3.0a1 (compat.check_schema(schema, "0.3.0a1")) or, in Python, checks hasattr(runs, "build_record"). There is no features id for them: ids describe worker and CLI behaviour that any host can read in the schema, while these are functions only a Python host imports.
Reserved inputs
A request's inputs may carry fields that are not tool parameters. Their names start with an underscore and belong to the protocol; a tool cannot declare a parameter with such a name (declaration error). A worker accepts every name that starts with an underscore and ignores the ones it does not know, so a newer host never fails an older worker. Tools never see reserved inputs. The list is labconstrictor_tools.protocol.RESERVED_INPUTS, tested against this table:
| Name | Sent by | Meaning |
|---|---|---|
_job_dir |
every host | the host-owned directory for outputs; the worker consumes it |
_calibration |
hosts that send a PixelSizeOf value |
per-axis pixel or voxel size with its provenance (x, y) |
_axes |
hosts that write a file without axes metadata | {param: "TZCYX"}, the axes of the file just written; reserved, no worker reads it yet |
A new name is added to RESERVED_INPUTS and to this table in the same change. The worker refuses exactly convert.undeclared_inputs(schema, inputs), the names that are neither declared nor reserved, with invalid_parameter.
Wire protocol (host <-> worker)
The worker (python -m labconstrictor_tools serve --module M) speaks the Appose worker protocol: one JSON object per line on stdin and stdout.
| Host sends | Worker answers |
|---|---|
{"task": id, "requestType": "EXECUTE", "script": "lc:<tool_id>", "inputs": {...}} |
LAUNCH, then UPDATE {message, current, maximum}*, then exactly one of COMPLETION {outputs}, FAILURE {error, code, traceback?}, CANCELATION |
{"task": id, "requestType": "CANCEL"} |
the task ends with CANCELATION if the tool calls check_cancel() |
Requests
taskmust be a non-empty string, unique until the task's terminal answer. AnEXECUTEthat reuses the id of a running task is ignored.scriptmust belc:<id>of a declared tool. Anything else, Python source included, is refused withunknown_tool. Ascriptthat is not text, orinputsthat is not an object (or absent), is refused withbad_request.inputs: image, labels, table, file and folder values are paths; an image may also be an Apposendarrayshared-memory object. Other values are JSON._job_dirnames the host-owned output directory.- A
CANCELfor a task that is not running is ignored, and not remembered for a laterEXECUTE. UnknownrequestTypes, lines that are not JSON objects and lines longer than 16 MiB are ignored. Each of these is written to the worker's log and stderr.
Answers
UPDATE {message, current, maximum}:maximumis 100 andcurrentis the whole percent nearest to the fraction the tool reported (progress(0.29)-> 29); a tie goes up (0.295 -> 30), as Java'sMath.rounddoes. A host that converts the fraction itself rounds the same way and never truncates.COMPLETION.outputs = {results: [...], job_dir, timings, diagnostics}. A result is{type, name, ...}:image/labels{path, axes},table {path},values {values},affine {matrix_yx, apply_to, relative_to},file {path}, andmessage,points,shapesas described under Results.- NaN and infinity cannot be written in JSON and are sent as
null. A host treatsnullin a numeric value as "not a finite number". - A tool that calls
sys.exit()or is interrupted ends withFAILURE(codeSystemExitorKeyboardInterrupt). A result that JSON cannot carry ends withFAILUREcodeunserializable_result. - A request written to a worker that has already exited ends as
CRASHEDwith the worker's last output. In the Python client,WorkerProcess.taskreturns that task; it is not kept inworker.tasksand no exception reaches the host.
Shared-memory images
- The descriptor is
{"appose_type": "ndarray", "shm": {"name"}, "shape", "dtype"}, optionally with"order". The block must still exist, be large enough and have a numeric dtype. A stale or malformed descriptor givesunreadable_image:the shared-memory image for 'N' is gone or malformed (...): the host must keep the block alive until the task ends and send {...}. - The host creates the block and unlinks it when it is done. The worker only maps and copies it, never unlinks it, and does not register it with its resource tracker.
order(featureshm_order_v1): absent,"C"or"C_ORDER"is row-major (last axis fastest, what numpy and a[Y, X]shape mean);"F"or"F_ORDER"is column-major (first axis fastest, what an ImgLib2-style[X, Y]array has). The tool receives the same logical array either way (array[i, j]is the element the host calls[i, j]), as a C-ordered copy. Any other value ("A","K","f", a number, a list,null) is refused withunreadable_imageand a message that sayssend 'C' or 'F', because a block read in the wrong order is the transposed image with no error. When in doubt, send a C-ordered block and[Y, X].
TIFF files
The worker memory-maps a TIFF input (copy-on-write) instead of reading it whole only when the file is at least 8 MiB and simple: one series with one pyramid level, uncompressed, untiled, all strips in one contiguous run in the machine's byte order, a generic, ImageJ or shaped TIFF (not OME, LSM or multi-file), not truncated. Any other file, or LC_TIFF_MEMMAP=0 in the worker's environment, is read the plain way. The tool cannot tell the difference: same shape, dtype and values, a writable numpy.ndarray. A tool that writes to its input changes only its private copy, never the file.
The worker releases every mapping before it sends the terminal answer, so the host can delete the input at once, also on Windows, where an open mapping locks the file (unless the tool keeps a reference to its input in a global). A host must not truncate or rewrite an input file while a task reads it: a mapped page beyond the end of a shortened file ends the worker.
Process lifetime
- Tools run on the worker's main thread. stdin is read on a helper thread; on Windows by polling, never a blocking read, because native libraries touch the stdin handle while they load and a pending read would deadlock them.
- Closing stdin means "the host is gone": running tools are asked to cancel and the worker exits within 10 s.
- Nothing a tool starts outlives the worker. On Windows the worker puts them in a kill-on-close job object. On POSIX the worker makes itself the leader of its own process group at start (
setsid, so no host has to) and, as its last act, sends SIGKILL to every other process of that group (found withps; if that fails, it kills the whole group, itself included).
Registry
An entry <name>.json is {name, display_name, version, prefix, python, module, pythonpath, runtime_path, schema_path, tools_version?, features?, hosts?, host_requirements?}. tools_version and features are copied from the schema (Tools version and features); hosts is the app's declaration, absent meaning listed in every host (App hosts); host_requirements is described in Host requirements.
Search order, first wins: $LC_HOME/apps (default ~/.labconstrictor/apps), the directories in $LC_APPS_PATH, then the system directory (%ProgramData%\LabConstrictor\apps, /Library/Application Support/LabConstrictor/apps or /etc/labconstrictor/apps).
An entry is skipped and reported when its interpreter is missing or not inside prefix, when its file is not owned by the user or is group- or world-writable (POSIX only), or when its schema is unreadable or has an unsupported protocol.