deepclause-sdk 0.0.89 → 0.1.0

package/src/prolog-src/deepclause_mi.pl

@@ -20,12 +20,78 @@
     create_engine/6,
     step_engine/4,
     destroy_engine/1,
+    % Frame predicates (M0: reentrant, frame-aware execution)
+    create_frame/6,
+    create_frame_raw/5,
+    step_frame/4,
+    end_frame/1,
+    frame_info/4,
+    default_frame/2,
+    % REPL session and query mode (M1)
+    create_session/4,
+    clear_session/1,
+    destroy_session/1,
+    load_code/3,
+    repl_initial_state/3,
+    query_start/5,
+    repl_solve/4,
+    collect_bindings/2,
+    repl_listing/2,
+    repl_listing/3,
+    repl_reserved/1,
+    % Freeze lock and export (M2)
+    repl_freeze/1,
+    repl_unfreeze/1,
+    repl_lock/1,
+    repl_is_frozen/1,
+    repl_try_unfreeze/2,
+    export_harness/3,
+    export_stats/4,
+    repl_script_files/2,
+    repl_materialize_embedded/1,
+    % Prompt mode (M3)
+    repl_meta_prompt/2,
+    repl_meta_prompt/3,
+    repl_extract_code/2,
+    repl_assert/3,
+    repl_assert_many/3,
+    repl_retract/3,
+    repl_define/4,
+    repl_delete_predicate/4,
+    repl_edit_touched/2,
+    repl_edit_touched_text/2,
+    repl_edit_touched_clear/1,
+    repl_set_dml_reference/2,
+    repl_set_authoring_examples/2,
+    repl_manifest/2,
+    repl_history_load/2,
+    repl_history_record/2,
+    repl_history_summary/2,
+    repl_rollback/3,
+    repl_user_predicates/2,
+    repl_user_predicates_text/2,
+    repl_predicate_arities/3,
+    repl_set_meta_catalog/2,
+    repl_set_meta_template/2,
+    repl_set_harness_examples/2,
+    repl_set_prolog_snippets/2,
+    repl_run_meta/4,
+    repl_snapshot_save/1,
+    repl_snapshot_restore/1,
+    repl_commit/3,
+    repl_last_commit_summary/2,
+    repl_execute_frame/4,
+    repl_record_meta/3,
+    repl_memory_term/3,
+    repl_get_memory/3,
+    repl_set_memory/3,
     post_agent_result/4,
     post_exec_result/3,
     post_sample_token_result/3,
     post_llm_result/3,
     post_judgment_result/3,
     provide_input/2,
+    provide_input_cancelled/1,
     mi/3,
     % Tool engine predicates for isolated tool execution
     create_tool_engine/4,
@@ -42,7 +108,25 @@
 :- discontiguous var_to_name/3.
 
 %% Dynamic predicates for session state (engine management only, not memory!)
-:- dynamic session_engine/2.       % session_engine(SessionId, Engine)
+:- dynamic session_engine/2.       % session_engine(SessionId, Engine) - legacy default engine handle
+:- dynamic session_frame/4.        % session_frame(FrameId, SessionId, Kind, Depth)
+:- dynamic session_frame_engine/2. % session_frame_engine(FrameId, Engine)
+:- dynamic session_default_frame/2. % session_default_frame(SessionId, FrameId)
+:- dynamic session_repl_memory/2.   % session_repl_memory(SessionId, HarnessMemory) - object/entry memory
+:- dynamic session_meta_memory/2.   % session_meta_memory(SessionId, MetaMemory) - code-writing task memory
+:- dynamic session_repl_mode/2.     % session_repl_mode(SessionId, true/false) - gates format/writeln output shims
+:- dynamic session_frozen/2.        % session_frozen(SessionId, true/false) - read-only lock
+:- dynamic session_locked/2.        % session_locked(SessionId, true/false) - irreversibly frozen (--locked)
+:- dynamic session_directive/2.     % session_directive(SessionId, Directive) - recorded :- directives for export
+:- dynamic session_meta_catalog/2.  % session_meta_catalog(SessionId, CatalogText) - host tool catalog for the meta prompt
+:- dynamic session_dml_reference/2. % session_dml_reference(SessionId, Text) - bundled DML reference for the meta prompt
+:- dynamic session_authoring_examples/2. % session_authoring_examples(SessionId, Text) - curated authoring patterns
+:- dynamic session_meta_template/2.  % session_meta_template(SessionId, Template) - bundled META_PROMPT.md template
+:- dynamic session_harness_examples/2. % session_harness_examples(SessionId, Text) - bundled HARNESS_EXAMPLES.md
+:- dynamic session_prolog_snippets/2. % session_prolog_snippets(SessionId, Text) - bundled PROLOG_SNIPPETS.md
+:- dynamic session_last_commit/2.    % session_last_commit(SessionId, [Name/Arity]) - predicates the last commit replaced
+:- dynamic session_edit_touched/2.   % session_edit_touched(SessionId, Name/Arity) - agent-mode edit transactions
+:- dynamic repl_snapshot/2.         % repl_snapshot(SessionId, Snapshot) - transactional edit snapshot
 :- dynamic session_params/2.       % session_params(SessionId, ParamsDict)
 :- dynamic session_user_tools/2.   % session_user_tools(SessionId, ToolName)
 :- dynamic session_user_tool_schema/3. % session_user_tool_schema(SessionId, ToolName, Schema)
@@ -56,6 +140,7 @@
 :- dynamic session_trace_enabled/2. % session_trace_enabled(SessionId, true/false)
 :- dynamic session_pending_signal/2. % session_pending_signal(SessionId, Signal) - fallback for engine_fetch
 :- dynamic session_user_input/2.   % session_user_input(SessionId, Input) - for ask_user tool
+:- dynamic session_input_cancelled/1. % session_input_cancelled(SessionId) - input/2 should fail (non-interactive)
 
 %% ============================================================
 %% DML Parsing
@@ -260,6 +345,182 @@ wrapper_type(list, array).
 wrapper_type(object, object).
 wrapper_type(dict, object).
 
+%% ============================================================
+%% Source-facing view of user clauses
+%%
+%% At load time task/N and prompt/N are rewritten to task_named/3 and
+%% prompt_named/3, and interpolated descriptions are hoisted into a preceding
+%% format/3. Those internal forms must not leak into listing/export — the meta
+%% task only knows task/N — so reverse them for display only.
+%% ============================================================
+
+%% clean_clause_body(+Body, -CleanBody)
+clean_clause_body(Body, Clean) :-
+    conj_list(Body, Goals),
+    clean_goal_list(Goals, CleanGoals),
+    (   CleanGoals = [Single]
+    ->  Clean = Single
+    ;   list_to_conjunction(CleanGoals, Clean)
+    ).
+
+conj_list((A, B), List) :-
+    !,
+    conj_list(A, LA),
+    conj_list(B, LB),
+    append(LA, LB, List).
+conj_list(Goal, [Goal]).
+
+clean_goal_list([], []) :- !.
+clean_goal_list([Goal], [Clean]) :-
+    !,
+    clean_atomic(Goal, Clean).
+clean_goal_list([First, Second | Rest], [CleanFirst | CleanRest]) :-
+    (   merge_interpolation(First, Second, CleanFirst)
+    ->  clean_goal_list(Rest, CleanRest)
+    ;   clean_atomic(First, CleanFirst),
+        clean_goal_list([Second | Rest], CleanRest)
+    ).
+
+%% merge_interpolation(+FormatGoal, +TaskGoal, -Merged)
+%% Fold `format(string(D), T, Args), task_named(D, ...)` back into
+%% `task("…{Var}…", ...)`.
+merge_interpolation(FormatGoal, TaskGoal, Merged) :-
+    FormatGoal = format(string(D), Template, Args),
+    (   TaskGoal = task_named(D, Vars, Infos)
+    ;   TaskGoal = prompt_named(D, Vars, Infos)
+    ),
+    task_functor(TaskGoal, Functor),
+    interpolate_template(Template, Args, Description),
+    clean_task(Functor, Description, Vars, Infos, Merged).
+
+task_functor(task_named(_, _, _), task).
+task_functor(prompt_named(_, _, _), prompt).
+
+clean_atomic(task_named(D, Vars, Infos), Clean) :-
+    !,
+    clean_task(task, D, Vars, Infos, Clean).
+clean_atomic(prompt_named(D, Vars, Infos), Clean) :-
+    !,
+    clean_task(prompt, D, Vars, Infos, Clean).
+clean_atomic((A ; B), (CA ; CB)) :-
+    !,
+    clean_clause_body(A, CA),
+    clean_clause_body(B, CB).
+clean_atomic((A -> B), (CA -> CB)) :-
+    !,
+    clean_clause_body(A, CA),
+    clean_clause_body(B, CB).
+clean_atomic((A -> B ; C), (CA -> CB ; CC)) :-
+    !,
+    clean_clause_body(A, CA),
+    clean_clause_body(B, CB),
+    clean_clause_body(C, CC).
+clean_atomic(\+(A), \+ CA) :-
+    !,
+    clean_clause_body(A, CA).
+clean_atomic(not(A), not(CA)) :-
+    !,
+    clean_clause_body(A, CA).
+% Wrappers: recurse into their goal arguments so a task/prompt inside is also
+% reversed (the load-time rewrite descends into these via transform_task_calls).
+clean_atomic(with_tools(Tools, Goal), with_tools(Tools, CleanGoal)) :-
+    !,
+    clean_clause_body(Goal, CleanGoal).
+clean_atomic(without_tools(Tools, Goal), without_tools(Tools, CleanGoal)) :-
+    !,
+    clean_clause_body(Goal, CleanGoal).
+clean_atomic(with_judgment(Backend, Goal), with_judgment(Backend, CleanGoal)) :-
+    !,
+    clean_clause_body(Goal, CleanGoal).
+clean_atomic(require_judgment(Backend, Goal), require_judgment(Backend, CleanGoal)) :-
+    !,
+    clean_clause_body(Goal, CleanGoal).
+clean_atomic(once(Goal), once(CleanGoal)) :-
+    !,
+    clean_clause_body(Goal, CleanGoal).
+clean_atomic(ignore(Goal), ignore(CleanGoal)) :-
+    !,
+    clean_clause_body(Goal, CleanGoal).
+clean_atomic(catch(Goal, Catcher, Recovery), catch(CleanGoal, Catcher, CleanRecovery)) :-
+    !,
+    clean_clause_body(Goal, CleanGoal),
+    clean_clause_body(Recovery, CleanRecovery).
+clean_atomic(forall(Generator, Action), forall(CleanGenerator, CleanAction)) :-
+    !,
+    clean_clause_body(Generator, CleanGenerator),
+    clean_clause_body(Action, CleanAction).
+clean_atomic(findall(Template, Goal, List), findall(Template, CleanGoal, List)) :-
+    !,
+    clean_clause_body(Goal, CleanGoal).
+clean_atomic(Module:Goal, Module:CleanGoal) :-
+    !,
+    clean_clause_body(Goal, CleanGoal).
+clean_atomic(Goal, Goal).
+
+%% clean_task(+Functor, +Description, +Vars, +Infos, -Clean)
+clean_task(Functor, Description, Vars, Infos, Clean) :-
+    clean_typed_args(Vars, Infos, CleanVars),
+    Clean =.. [Functor, Description | CleanVars].
+
+clean_typed_args([], [], []) :- !.
+clean_typed_args([Var | Vars], [Info | Infos], [Wrapped | Wrappeds]) :-
+    !,
+    typed_arg(Var, Info, Wrapped),
+    clean_typed_args(Vars, Infos, Wrappeds).
+clean_typed_args(Vars, _, Vars).
+
+%% typed_arg(+Var, +Info, -Wrapped) — reverse typed_var{...} to its wrapper.
+typed_arg(Var, Info, Wrapped) :-
+    is_dict(Info),
+    get_dict(type, Info, Type),
+    !,
+    typed_arg_type(Type, Var, Info, Wrapped).
+typed_arg(Var, _, Var).
+
+typed_arg_type(string, Var, _, Var) :- !.
+typed_arg_type(integer, Var, _, integer(Var)) :- !.
+typed_arg_type(number, Var, _, number(Var)) :- !.
+typed_arg_type(boolean, Var, _, boolean(Var)) :- !.
+typed_arg_type(object, Var, _, object(Var)) :- !.
+typed_arg_type(array, Var, Info, list(Wrapped)) :-
+    !,
+    (   get_dict(itemType, Info, ItemType)
+    ->  true
+    ;   ItemType = string
+    ),
+    Wrapped =.. [ItemType, Var].
+typed_arg_type(_, Var, _, Var).
+
+%% interpolate_template(+Template, +Args, -Description)
+%% Reverse of the {Var} -> ~w hoist. Succeeds only when every placeholder is a
+%% plain variable, so the caller can fall back to keeping the format/3 goal.
+interpolate_template(Template, Args, Description) :-
+    string(Template),
+    string_codes(Template, Codes),
+    interpolate_codes(Codes, Args, OutCodes),
+    string_codes(Description, OutCodes).
+
+interpolate_codes([], [], []) :- !.
+%% A {Var} placeholder consumes one argument; require Args to be exhausted
+%% exactly (the []/[] base case above fails if either side has leftovers).
+interpolate_codes([0'~, 0'w | Rest], [Arg | Args], Out) :-
+    !,
+    named_var(Arg),
+    term_string(Arg, Name, [numbervars(true)]),
+    string_codes(Name, NameCodes),
+    interpolate_codes(Rest, Args, Tail),
+    append([0'{|NameCodes], [0'}|Tail], Out).
+interpolate_codes([0'~, 0'~ | Rest], Args, [0'~ | Out]) :-
+    !,
+    interpolate_codes(Rest, Args, Out).
+interpolate_codes([Code | Rest], Args, [Code | Out]) :-
+    interpolate_codes(Rest, Args, Out).
+
+%% An interpolation argument is a variable or a `$VAR(N)` term (after
+%% numbervars), both of which print as a stable name (A, B, ...).
+named_var(Arg) :- var(Arg), !.
+named_var('$VAR'(_)).
+
 %% var_to_name(+Bindings, +Var, -Name)
 %% Look up a variable's name from the bindings list
 var_to_name(Bindings, Var, Name) :-
@@ -269,7 +530,15 @@ var_to_name(Bindings, Var, Name) :-
     ).
 
 %% process_clause(+Term, +SessionId)
-%% Process a single clause and add to session
+%% Process a single clause and add to session.
+%% Reject reserved-name definitions (third place of the reserved guard, so
+%% consulted/generated code cannot shadow the REPL control surface).
+process_clause(Term, _SessionId) :-
+    repl_reserved_clause(Term),
+    !,
+    throw(error(permission_error(modify, reserved_name, Term),
+                context(process_clause/2, 'reserved predicate'))).
+
 process_clause((:- Directive), SessionId) :-
     !,
     process_directive(Directive, SessionId).
@@ -281,8 +550,9 @@ process_clause((tool(ToolHead, Description) :- Body), SessionId) :-
     extract_tool_schema(ToolHead, Description, ToolName, Schema),
     assertz(session_user_tools(SessionId, ToolName)),
     assertz(session_user_tool_schema(SessionId, ToolName, Schema)),
-    % Store the source code for the tool description
-    format(string(SourceCode), "tool(~w, ~q) :-~n    ~w.", [ToolHead, Description, Body]),
+    % Store the source code for the tool description. Reverses the load-time
+    % task/prompt rewrites and normalizes variables for deterministic export.
+    format_tool_source(ToolHead, Description, Body, SourceCode),
     assertz(SessionId:tool_source(ToolName, SourceCode)),
     % Assert the tool implementation (use just ToolHead for execution)
     assertz(SessionId:(tool(ToolHead) :- ExpandedBody)).
@@ -294,8 +564,8 @@ process_clause((tool(ToolHead) :- Body), SessionId) :-
     extract_tool_schema(ToolHead, none, ToolName, Schema),
     assertz(session_user_tools(SessionId, ToolName)),
     assertz(session_user_tool_schema(SessionId, ToolName, Schema)),
-    % Store the source code for the tool description
-    format(string(SourceCode), "tool(~w) :-~n    ~w.", [ToolHead, Body]),
+    % Store the source code for the tool description (reverses task rewrites).
+    format_tool_source(ToolHead, none, Body, SourceCode),
     assertz(SessionId:tool_source(ToolName, SourceCode)),
     % Assert the tool implementation
     assertz(SessionId:(tool(ToolHead) :- ExpandedBody)).
@@ -309,6 +579,15 @@ process_clause((Head :- Body), SessionId) :-
     ),
     assertz(SessionId:(Head :- ExpandedBody)).
 
+%% repl_delete/1 is a load-time directive that removes a predicate. It must
+%% be handled before the generic fact clause so it is never asserted itself.
+process_clause(repl_delete(Name/Arity), SessionId) :-
+    !,
+    (   atom(Name), integer(Arity)
+    ->  catch(abolish(SessionId:Name/Arity), _, true)
+    ;   true
+    ).
+
 process_clause(Fact, SessionId) :-
     % Simple fact
     assertz(SessionId:Fact).
@@ -426,15 +705,27 @@ workspace_module_reference(Module) :-
 process_use_module_directive(Module, SessionId) :-
     (   workspace_module_reference(Module)
     ->  process_directive(consult(Module), SessionId)
-    ;   SessionId:use_module(Module)
+    ;   SessionId:use_module(Module),
+        import_library_into_mi(Module)
     ).
 
 process_use_module_directive(Module, Exports, SessionId) :-
     (   workspace_module_reference(Module)
     ->  process_directive(consult(Module), SessionId)
-    ;   SessionId:use_module(Module, Exports)
+    ;   SessionId:use_module(Module, Exports),
+        import_library_into_mi(Module)
     ).
 
+%% System libraries are also imported into the meta-interpreter module itself,
+%% so meta-calls (`call_with_inference_limit/3`, `once/1`, `catch/3`, ...) can
+%% resolve them. Without this, `call_with_inference_limit(label(Xs), ...)` fails
+%% with `existence_error(deepclause_mi:label/1)` because clpfd was imported only
+%% into the session module.
+import_library_into_mi(library(Name)) :-
+    !,
+    catch(deepclause_mi:use_module(library(Name)), _, true).
+import_library_into_mi(_).
+
 %% process_directive(+Directive, +SessionId)
 process_directive(param(Key, Desc), SessionId) :-
     !,
@@ -454,9 +745,17 @@ process_directive(consult(File), SessionId) :-
 %% Handle use_module directive
 process_directive(use_module(Module), SessionId) :-
     !,
+    (   workspace_module_reference(Module)
+    ->  true
+    ;   record_directive(SessionId, use_module(Module))
+    ),
     process_use_module_directive(Module, SessionId).
 process_directive(use_module(Module, Exports), SessionId) :-
     !,
+    (   workspace_module_reference(Module)
+    ->  true
+    ;   record_directive(SessionId, use_module(Module, Exports))
+    ),
     process_use_module_directive(Module, Exports, SessionId).
 %% Handle list-style consult: :- [File] or :- [File1, File2, ...]
 process_directive([File|Files], SessionId) :-
@@ -473,6 +772,9 @@ process_directive(_, _).
 %% create_engine(+SessionId, +MemoryId, +Args, +Params, +InitialMemory, -Engine)
 %% Args is a list of positional arguments for agent_main
 %% Params is a dict of named parameters (already asserted as param/2 facts)
+%%
+%% The engine is registered as the session's default `query` frame so that
+%% step_engine/4 keeps working as a thin wrapper over step_frame/4.
 create_engine(SessionId, _MemoryId, Args, Params, InitialMemory, Engine) :-
     assertz(session_params(SessionId, Params)),
     determine_agent_goal(SessionId, Args, Goal),
@@ -484,12 +786,1631 @@ create_engine(SessionId, _MemoryId, Args, Params, InitialMemory, Engine) :-
     (get_dict(gas_limit, Params, GasLimit) -> true ; GasLimit = -1),
     % Create initial state with provided memory, params, context stack, trace depth and gas
     InitialState = state{memory: InitialMemory, params: Params, context_stack: [], depth: 0, gas_remaining: GasLimit},
-    % Create the engine - pass SessionId and initial state to mi/3
-    engine_create(_, 
-        deepclause_mi:mi(Goal, InitialState, SessionId),
-        Engine),
+    create_frame(SessionId, query, 0, Goal, InitialState, FrameId),
+    retractall(session_default_frame(SessionId, _)),
+    assertz(session_default_frame(SessionId, FrameId)),
+    session_frame_engine(FrameId, Engine),
+    retractall(session_engine(SessionId, _)),
     assertz(session_engine(SessionId, Engine)).
 
+%% ============================================================
+%% Frames (re-entrant execution)
+%% ============================================================
+%%
+%% Historically a session owned exactly one engine (session_engine/2).
+%% Prompt mode requires nested engines: a meta frame that calls `execute`
+%% which runs a child frame, which may itself call task() and spawn a
+%% further frame. A frame is therefore (FrameId, SessionId, Kind, Depth)
+%% with its engine stored in session_frame_engine/2.
+%%
+%% The legacy step_engine/4 resolves the session's default query frame and
+%% delegates to step_frame/4, so single-engine callers are unaffected.
+
+default_frame(SessionId, FrameId) :-
+    session_default_frame(SessionId, FrameId).
+
+%% frame_info(+FrameId, -SessionId, -Kind, -Depth)
+frame_info(FrameId, SessionId, Kind, Depth) :-
+    session_frame(FrameId, SessionId, Kind, Depth).
+
+%% create_frame_raw(+SessionId, +Kind, +Depth, +EngineGoal, -FrameId)
+%% Registers a frame whose engine runs EngineGoal verbatim. Most callers want
+%% create_frame/6, which wraps the goal in the mi/3 meta-interpreter; goal mode
+%% uses this to run repl_solve/4 directly (mi/3 cuts after the first solution).
+create_frame_raw(SessionId, Kind, Depth, EngineGoal, FrameId) :-
+    gensym(frame_, FrameId),
+    engine_create(_, EngineGoal, Engine),
+    assertz(session_frame(FrameId, SessionId, Kind, Depth)),
+    assertz(session_frame_engine(FrameId, Engine)).
+
+%% create_frame(+SessionId, +Kind, +Depth, +Goal, +InitialState, -FrameId)
+%% Kind = query | meta | nested | object
+%% Creates an engine running deepclause_mi:mi(Goal, InitialState, SessionId)
+%% and registers it as a frame. The caller is responsible for depth-first
+%% stepping: a parent frame is suspended while a child frame runs, so the
+%% per-session result/signal slots are never concurrently pending.
+create_frame(SessionId, Kind, Depth, Goal, InitialState, FrameId) :-
+    create_frame_raw(SessionId, Kind, Depth,
+        deepclause_mi:mi(Goal, InitialState, SessionId),
+        FrameId).
+
+%% step_frame(+FrameId, -Status, -Content, -Payload)
+step_frame(FrameId, Status, Content, Payload) :-
+    (   session_frame(FrameId, SessionId, _Kind, _Depth),
+        session_frame_engine(FrameId, Engine)
+    ->  step_engine_handle(SessionId, Engine, Status, Content, Payload)
+    ;   Status = error,
+        Content = 'No engine found for frame',
+        Payload = none
+    ).
+
+%% step_engine_handle(+SessionId, +Engine, -Status, -Content, -Payload)
+%% Shared stepping logic for both step_frame/4 and the legacy step_engine/4.
+step_engine_handle(SessionId, Engine, Status, Content, Payload) :-
+    catch(
+        (   engine_next(Engine, Result)
+        ->  process_engine_result(Result, Status, Content, Payload)
+        ;   % Engine finished - return trace if enabled
+            Status = finished,
+            Content = '',
+            (   session_trace_enabled(SessionId, true),
+                session_trace_log(SessionId, TraceLog)
+            ->  Payload = payload{trace: TraceLog}
+            ;   Payload = none
+            )
+        ),
+        Error,
+        (   format(atom(ErrMsg), 'Engine error: ~w', [Error]),
+            Status = error,
+            Content = ErrMsg,
+            (   session_trace_enabled(SessionId, true),
+                session_trace_log(SessionId, TraceLog)
+            ->  Payload = payload{trace: TraceLog}
+            ;   Payload = none
+            )
+        )
+    ).
+
+%% end_frame(+FrameId)
+%% Destroys the frame's engine and unregisters the frame. Also clears the
+%% session's default-frame pointer if this frame was the default.
+end_frame(FrameId) :-
+    (   session_frame_engine(FrameId, Engine)
+    ->  catch(engine_destroy(Engine), _, true)
+    ;   true
+    ),
+    (   session_frame(FrameId, SessionId, _, _)
+    ->  retractall(session_default_frame(SessionId, FrameId))
+    ;   true
+    ),
+    retractall(session_frame_engine(FrameId, _)),
+    retractall(session_frame(FrameId, _, _, _)).
+
+%% ============================================================
+%% REPL Session and Goal Mode (M1)
+%% ============================================================
+%%
+%% A REPL session owns a persistent living module. Unlike create_engine/6,
+%% which is tied to a single run and destroyed by destroy_engine/1, a session
+%% lives across inputs; reset/clear_session empties it without tearing down the
+%% process-level SWI instance.
+
+%% create_session(+SessionId, +Params, +HarnessMemory, +MetaMemory)
+create_session(SessionId, Params, HarnessMemory, MetaMemory) :-
+    retractall(session_params(SessionId, _)),
+    assertz(session_params(SessionId, Params)),
+    (   get_dict(trace, Params, true)
+    ->  TraceEnabled = true
+    ;   TraceEnabled = false
+    ),
+    retractall(session_trace_enabled(SessionId, _)),
+    assertz(session_trace_enabled(SessionId, TraceEnabled)),
+    retractall(session_trace_log(SessionId, _)),
+    assertz(session_trace_log(SessionId, [])),
+    retractall(session_repl_memory(SessionId, _)),
+    assertz(session_repl_memory(SessionId, HarnessMemory)),
+    retractall(session_meta_memory(SessionId, _)),
+    assertz(session_meta_memory(SessionId, MetaMemory)),
+    retractall(session_repl_mode(SessionId, _)),
+    assertz(session_repl_mode(SessionId, true)),
+    retractall(session_frozen(SessionId, _)),
+    assertz(session_frozen(SessionId, false)),
+    retractall(session_locked(SessionId, _)),
+    assertz(session_locked(SessionId, false)).
+
+%% repl_abolish_user_predicates(+SessionId)
+%% Removes only the harness's own predicates; imported builtins are untouched.
+repl_abolish_user_predicates(SessionId) :-
+    (   current_module(SessionId)
+    ->  findall(Name/Arity,
+            (   current_predicate(SessionId:Name/Arity),
+                repl_user_predicate(SessionId, Name, Arity)
+            ),
+            UserPreds0),
+        sort(UserPreds0, UserPreds),
+        forall(member(Name/Arity, UserPreds),
+            catch(abolish(SessionId:Name/Arity), _, true))
+    ;   true
+    ).
+
+%% clear_session(+SessionId)
+%% Empties the living module, ends all frames, and resets memories. Session
+%% params (workspace/gas limit) are preserved so the REPL stays configured.
+clear_session(SessionId) :-
+    (   findall(FrameId, session_frame(FrameId, SessionId, _, _), FrameIds)
+    ->  forall(member(FrameId, FrameIds), end_frame(FrameId))
+    ;   true
+    ),
+    (   session_engine(SessionId, Engine)
+    ->  catch(engine_destroy(Engine), _, true)
+    ;   true
+    ),
+    retractall(session_engine(SessionId, _)),
+    retractall(session_default_frame(SessionId, _)),
+    retractall(session_repl_memory(SessionId, _)),
+    assertz(session_repl_memory(SessionId, [])),
+    retractall(session_meta_memory(SessionId, _)),
+    assertz(session_meta_memory(SessionId, [])),
+    retractall(repl_snapshot(SessionId, _)),
+    retractall(session_user_tools(SessionId, _)),
+    retractall(session_user_tool_schema(SessionId, _, _)),
+    repl_abolish_user_predicates(SessionId).
+
+%% destroy_session(+SessionId)
+%% Tears a REPL session down completely: clears the module/frames and removes
+%% the session's dynamic bookkeeping so the process can host another session.
+destroy_session(SessionId) :-
+    clear_session(SessionId),
+    retractall(session_repl_memory(SessionId, _)),
+    retractall(session_meta_memory(SessionId, _)),
+    retractall(session_repl_mode(SessionId, _)),
+    retractall(session_frozen(SessionId, _)),
+    retractall(session_locked(SessionId, _)),
+    retractall(session_directive(SessionId, _)),
+    retractall(session_meta_catalog(SessionId, _)),
+    retractall(session_dml_reference(SessionId, _)),
+    retractall(session_authoring_examples(SessionId, _)),
+    retractall(session_meta_template(SessionId, _)),
+    retractall(session_harness_examples(SessionId, _)),
+    retractall(session_prolog_snippets(SessionId, _)),
+    retractall(session_last_commit(SessionId, _)),
+    retractall(repl_snapshot(SessionId, _)),
+    retractall(session_params(SessionId, _)),
+    retractall(session_trace_enabled(SessionId, _)),
+    retractall(session_trace_log(SessionId, _)).
+
+%% load_code(+SessionId, +Code, -Error)
+%% Parses DML source into the session module, running the normal source
+%% preprocessing (task/prompt rewrite, interpolation, expand_term).
+load_code(SessionId, Code, Error) :-
+    catch(
+        (   guard_not_frozen(SessionId),
+            parse_dml_string(Code, SessionId),
+            Error = none
+        ),
+        LoadError,
+        format(atom(Error), '~w', [LoadError])
+    ).
+
+%% repl_initial_state(+SessionId, +FrameKind, -InitialState)
+%% Builds the state{} threaded through a REPL frame. M1 seeds harness memory
+%% from session_repl_memory/2; M4 adds the meta/scratch slots.
+repl_initial_state(SessionId, FrameKind, InitialState) :-
+    session_params(SessionId, Params),
+    (   get_dict(gas_limit, Params, GasLimit)
+    ->  true
+    ;   GasLimit = -1
+    ),
+    % Two-level memory: meta (code-writing) and harness (runtime) are kept
+    % apart. The state carries the slot so write-back goes to the right one.
+    (   FrameKind == meta
+    ->  MemorySlot = meta,
+        (   session_meta_memory(SessionId, Memory)
+        ->  true
+        ;   Memory = []
+        )
+    ;   MemorySlot = harness,
+        (   session_repl_memory(SessionId, Memory)
+        ->  true
+        ;   Memory = []
+        )
+    ),
+    InitialState = state{
+        memory: Memory,
+        params: Params,
+        context_stack: [],
+        depth: 0,
+        gas_remaining: GasLimit,
+        memory_slot: MemorySlot,
+        frame_kind: FrameKind
+    }.
+
+%% query_start(+SessionId, +Text, +FrameKind, +InitialState, -Error)
+%% Parses and preprocesses a goal string, then creates a frame running
+%% repl_solve/4. The frame becomes the session's default frame so that
+%% step_engine/4 and the runner can drive it.
+query_start(SessionId, Text, FrameKind, InitialState, Error) :-
+    catch(
+        (   read_repl_goal(SessionId, Text, Goal, Names),
+            create_frame_raw(SessionId, FrameKind, 0,
+                deepclause_mi:repl_solve(Goal, Names, SessionId, InitialState),
+                FrameId),
+            retractall(session_default_frame(SessionId, _)),
+            assertz(session_default_frame(SessionId, FrameId)),
+            session_frame_engine(FrameId, Engine),
+            retractall(session_engine(SessionId, _)),
+            assertz(session_engine(SessionId, Engine)),
+            Error = none
+        ),
+        QueryError,
+        format(atom(Error), '~w', [QueryError])
+    ).
+
+%% ensure_full_stop(+Text, -TextWithStop)
+%% Appends a terminating full stop + newline when the goal text lacks one, so
+%% both `goal: p(X).` and `-g "p(X)"` read cleanly.
+ensure_full_stop(Text, Text1) :-
+    atom_string(TextAtom, Text),
+    (   atom_ends_with_stop(TextAtom)
+    ->  atom_concat(TextAtom, '\n', Text1)
+    ;   atom_concat(TextAtom, '.\n', Text1)
+    ).
+
+%% atom_ends_with_stop(+Atom)
+%% True when the last non-whitespace character is a full stop. A naive
+%% "ends with ." test would append an extra full stop to any block that ends
+%% with a newline, and read_term/3 then fails on the lone '.' (end_of_clause).
+atom_ends_with_stop(TextAtom) :-
+    atom_string(TextAtom, TextStr),
+    string_length(TextStr, Len0),
+    trim_trailing_ws(TextStr, Len0, Len),
+    Len > 0,
+    Pos is Len - 1,
+    sub_string(TextStr, Pos, 1, _, ".").
+
+trim_trailing_ws(Str, Len0, Len) :-
+    (   Len0 > 0,
+        Pos is Len0 - 1,
+        sub_string(Str, Pos, 1, _, Ch),
+        ( Ch == " " ; Ch == "\t" ; Ch == "\n" ; Ch == "\r" )
+    ->  Len1 is Len0 - 1,
+        trim_trailing_ws(Str, Len1, Len)
+    ;   Len = Len0
+    ).
+
+%% read_repl_goal(+SessionId, +Text, -Goal, -Names)
+%% Names is the read_term variable_names list (Name=Var), used to render
+%% bindings for solution events.
+read_repl_goal(SessionId, Text, Goal, Names) :-
+    % read_term/3 requires a full stop; REPL callers may omit it (`-g "p(X)"`).
+    ensure_full_stop(Text, Text1),
+    open_string(Text1, Stream),
+    read_term(Stream, RawGoal, [module(SessionId), variable_names(Names0)]),
+    close(Stream),
+    (   RawGoal == end_of_file
+    ->  throw(error(syntax_error('empty goal'), _))
+    ;   true
+    ),
+    % Apply only the goal-relevant source transforms. Do NOT run
+    % preprocess_loaded_term/3 here: its file-load term expansion flattens a
+    % list goal such as ["file.dml"] into its elements.
+    transform_task_calls(RawGoal, Names0, Transformed),
+    % Use the body expander (not expand_term_interp/3) so a `{Var}` string is
+    % hoisted into a goal *before* the goal that uses it. expand_term_interp
+    % embeds the interpolation term in the argument position instead, which is
+    % wrong for a raw goal such as verify(X, "Is {X} > 0?", V).
+    expand_body_interp(Transformed, Names0, Goal),
+    Names = Names0.
+
+%% repl_solve(+Goal, +Names, +SessionId, +State)
+%% Enumerating goal-mode solver. Yields one solution(Bindings, Deterministic)
+%% per answer and fails so engine_next/2 backtracks for the next solution.
+%% answer/1 commits (throws '$answer_commit') and stops enumeration.
+%% mi/3 is deliberately not used: it cuts after the first solution.
+repl_solve(Goal, Names, SessionId, State) :-
+    nb_setval(current_session_id, SessionId),
+    catch(
+        repl_solve_loop(Goal, Names, SessionId, State),
+        '$answer_commit',
+        true
+    ).
+
+repl_solve_loop(Goal, Names, SessionId, State) :-
+    mi_call(Goal, State, StateOut),
+    collect_bindings(Names, Bindings),
+    store_memory_for_state(SessionId, StateOut),
+    engine_yield(solution(Bindings, false)),
+    fail.
+
+%% collect_bindings(+Names, -Bindings)
+%% Bindings is a list of Name-RenderedText. Unbound variables render as '_'.
+collect_bindings(Names, Bindings) :-
+    findall(Name-Text,
+        (   member(Name=Var, Names),
+            render_binding(Var, Text)
+        ),
+        Bindings).
+
+render_binding(Var, '_') :-
+    var(Var),
+    !.
+render_binding(Value, Text) :-
+    with_output_to(string(Text), write_term(Value, [quoted(true), max_depth(20)])).
+
+%% store_memory_for_state(+SessionId, +State)
+%% Writes the threaded memory back to the slot named by the state.
+store_memory_for_state(SessionId, State) :-
+    (   is_dict(State),
+        get_dict(memory, State, Memory)
+    ->  (   get_dict(memory_slot, State, meta)
+        ->  retractall(session_meta_memory(SessionId, _)),
+            assertz(session_meta_memory(SessionId, Memory))
+        ;   retractall(session_repl_memory(SessionId, _)),
+            assertz(session_repl_memory(SessionId, Memory))
+        )
+    ;   true
+    ).
+
+%% repl_listing(+SessionId, +Filter, -Text)
+%% Read-only listing used by the meta tool and the `listing.` REPL command.
+repl_listing(SessionId, Filter, Text) :-
+    with_output_to(string(Text), repl_listing_output(SessionId, Filter)).
+
+%% repl_listing(+Filter, -Text) uses the current session id.
+repl_listing(Filter, Text) :-
+    get_session_id(SessionId),
+    repl_listing(SessionId, Filter, Text).
+
+repl_listing_output(SessionId, Filter) :-
+    (   Filter == tools
+    ->  forall(session_user_tool_schema(SessionId, Name, Schema),
+            (   SessionId:tool_source(Name, Source)
+            ->  format("~w - ~w~n~w~n~n", [Name, Schema, Source])
+            ;   format("~w - ~w~n~n", [Name, Schema])
+            )
+        )
+    ;   Filter == history
+    ->  repl_history_listing(SessionId)
+    ;   (   current_predicate(SessionId:module_doc/1),
+            SessionId:module_doc(Skill)
+        ->  format("skill: ~w~n~n", [Skill])
+        ;   true
+        ),
+        findall(Name/Arity,
+            (   current_predicate(SessionId:Name/Arity),
+                repl_user_predicate(SessionId, Name, Arity)
+            ),
+            Preds0),
+        sort(Preds0, Preds),
+        forall(member(Name/Arity, Preds),
+            (   repl_listing_match(Filter, Name, Arity)
+            ->  format("~w/~w~n", [Name, Arity]),
+                (   current_predicate(SessionId:doc/2),
+                    SessionId:doc(Name/Arity, DocText)
+                ->  format("  % ~w~n", [DocText])
+                ;   true
+                ),
+                functor(Head, Name, Arity),
+                forall(clause(SessionId:Head, ClauseBody), print_user_clause(Head, ClauseBody))
+            ;   true
+            )
+        )
+    ).
+
+repl_listing_match(all, _, _) :- !.
+repl_listing_match(Name/Arity, Name, Arity) :- !.
+repl_listing_match(Filter, Name, _) :-
+    atom(Filter),
+    !,
+    (   sub_atom(Name, 0, _, _, Filter)
+    ;   sub_atom(Filter, 0, _, _, Name)
+    ).
+repl_listing_match(_, _, _).
+
+%% repl_user_predicate(+SessionId, +Name, +Arity)
+%% Excludes reserved and internal predicates from listing/export.
+repl_user_predicate(_SessionId, Name, _Arity) :-
+    repl_reserved_name(Name),
+    !,
+    fail.
+repl_user_predicate(_SessionId, Name, _Arity) :-
+    internal_session_predicate(Name),
+    !,
+    fail.
+repl_user_predicate(_SessionId, Name, _Arity) :-
+    history_predicate(Name),
+    !,
+    fail.
+repl_user_predicate(SessionId, Name, Arity) :-
+    % User DML clauses are asserted (interpreted) into the session module.
+    % Exclude predicates imported via use_module (e.g. library(clpfd)) and
+    % foreign/builtin predicates. Build a callable head rather than a predicate
+    % indicator: predicate_property/2 wants a goal (Module:Goal).
+    functor(Head, Name, Arity),
+    predicate_property(SessionId:Head, interpreted),
+    \+ predicate_property(SessionId:Head, imported_from(_)),
+    \+ predicate_property(SessionId:Head, foreign).
+
+internal_session_predicate(param).
+internal_session_predicate(param_decl).
+internal_session_predicate(tool_source).
+internal_session_predicate('__session__').
+
+%% history_predicate(+Name)
+%% Runtime-owned harness-history facts. Excluded from the user predicate set (so
+%% they are neither listed as harness predicates nor exported nor replaced by a
+%% commit) and protected from user definition -- but CALLABLE from DML, so the
+%% harness can query what happened in previous sessions.
+history_predicate(Name) :-
+    atom(Name),
+    sub_atom(Name, 0, _, _, harness_).
+
+%% repl_reserved_name(+Name)
+%% Names owned by the REPL runtime. M4 uses repl_reserved/1 to refuse goals
+%% that try to re-enter or shadow the REPL control surface.
+%% Any repl_*/meta_* name is reserved (namespace guard), plus the explicit
+%% control names below. repl_delete is a protected exception for definition
+%% purposes (see repl_protected_name/1).
+repl_reserved_name(Name) :-
+    atom(Name),
+    (   sub_atom(Name, 0, _, _, repl_)
+    ;   sub_atom(Name, 0, _, _, meta_)
+    ).
+
+repl_reserved_name(repl_meta_prompt).
+repl_reserved_name(repl_extract_code).
+repl_reserved_name(repl_reserved).
+repl_reserved_name(repl_reserved_name).
+repl_reserved_name(repl_tool_catalog).
+repl_reserved_name(repl_listing).
+repl_reserved_name(repl_assert).
+repl_reserved_name(repl_retract).
+repl_reserved_name(repl_delete).
+repl_reserved_name(repl_freeze).
+repl_reserved_name(repl_unfreeze).
+repl_reserved_name(repl_is_frozen).
+repl_reserved_name(repl_solve).
+repl_reserved_name(repl_initial_state).
+repl_reserved_name(repl_user_predicate).
+repl_reserved_name(query_start).
+repl_reserved_name(read_repl_goal).
+repl_reserved_name(create_session).
+repl_reserved_name(clear_session).
+repl_reserved_name(destroy_session).
+repl_reserved_name(create_frame).
+repl_reserved_name(create_frame_raw).
+repl_reserved_name(step_frame).
+repl_reserved_name(end_frame).
+repl_reserved_name(frame_info).
+repl_reserved_name(default_frame).
+repl_reserved_name(load_code).
+repl_reserved_name(freeze).
+repl_reserved_name(unfreeze).
+repl_reserved_name(reset).
+repl_reserved_name(export).
+
+%% repl_reserved(+TermOrNameArity)
+repl_reserved(Name) :-
+    atom(Name),
+    repl_reserved_name(Name).
+repl_reserved(Name/Arity) :-
+    atom(Name),
+    integer(Arity),
+    repl_reserved_name(Name).
+repl_reserved(Term) :-
+    compound(Term),
+    functor(Term, Name, _),
+    repl_reserved_name(Name).
+
+%% ============================================================
+%% Freeze Lock and Export (M2)
+%% ============================================================
+
+%% repl_freeze(+SessionId)
+%% Makes the living module read-only. Queries, `execute`, and nested task()
+%% calls still work; only mutation is refused.
+repl_freeze(SessionId) :-
+    retractall(session_frozen(SessionId, _)),
+    assertz(session_frozen(SessionId, true)).
+
+%% repl_lock(+SessionId)
+%% Irreversibly freezes: repl_unfreeze/1 refuses. Used by --locked.
+repl_lock(SessionId) :-
+    repl_freeze(SessionId),
+    retractall(session_locked(SessionId, _)),
+    assertz(session_locked(SessionId, true)).
+
+%% repl_unfreeze(+SessionId)
+repl_unfreeze(SessionId) :-
+    (   session_locked(SessionId, true)
+    ->  throw(error(permission_error(modify, locked_harness, SessionId),
+                context(repl_unfreeze/1, 'harness is locked; unfreeze is disabled')))
+    ;   retractall(session_frozen(SessionId, _)),
+        assertz(session_frozen(SessionId, false))
+    ).
+
+%% repl_is_frozen(+SessionId)
+repl_is_frozen(SessionId) :-
+    session_frozen(SessionId, true),
+    !.
+
+%% repl_try_unfreeze(+SessionId, -Error)
+%% Non-throwing wrapper so the host can report a locked harness cleanly.
+repl_try_unfreeze(SessionId, Error) :-
+    catch(repl_unfreeze(SessionId), UnfreezeError,
+        format(atom(Error), '~w', [UnfreezeError])),
+    (   var(Error)
+    ->  Error = none
+    ;   true
+    ).
+
+%% guard_not_frozen(+SessionId)
+%% Shared mutation guard for assert/retract/consult/load.
+guard_not_frozen(SessionId) :-
+    (   session_frozen(SessionId, true)
+    ->  throw(error(permission_error(modify, frozen_harness, SessionId),
+                context(mi_call/3, 'harness is frozen; assert/retract/load are disabled')))
+    ;   true
+    ).
+
+%% record_directive(+SessionId, +Directive)
+record_directive(SessionId, Directive) :-
+    (   session_directive(SessionId, Directive)
+    ->  true
+    ;   assertz(session_directive(SessionId, Directive))
+    ).
+
+%% ---- Export (serialization) ----
+
+%% export_harness(+SessionId, +Header, -Text)
+%% Deterministically serialize the living module into self-contained DML:
+%% directives, tools, embedded scripts, then user predicates sorted name/arity.
+export_harness(SessionId, Header, Text) :-
+    with_output_to(string(Text), export_harness_output(SessionId, Header)).
+
+export_harness_output(SessionId, Header) :-
+    (   Header == none
+    ->  true
+    ;   format("% ~w~n", [Header])
+    ),
+    export_directives(SessionId),
+    export_tools(SessionId),
+    export_clauses(SessionId).
+
+export_directives(SessionId) :-
+    findall(Directive, session_directive(SessionId, Directive), Directives0),
+    sort(Directives0, Directives),
+    forall(member(Directive, Directives), format(":- ~q.~n", [Directive])),
+    (   Directives == []
+    ->  true
+    ;   nl
+    ).
+
+export_tools(SessionId) :-
+    findall(Name, session_user_tool_schema(SessionId, Name, _), Names0),
+    sort(Names0, Names),
+    forall(member(Name, Names),
+        (   SessionId:tool_source(Name, Source)
+        ->  format("~w~n~n", [Source])
+        ;   true
+        )).
+
+export_clauses(SessionId) :-
+    findall(Name/Arity,
+        (   current_predicate(SessionId:Name/Arity),
+            export_user_predicate(SessionId, Name, Arity)
+        ),
+        Preds0),
+    sort(Preds0, Preds),
+    forall(member(Name/Arity, Preds),
+        (   functor(Head, Name, Arity),
+            forall(clause(SessionId:Head, Body), export_clause(Head, Body))
+        )).
+
+export_user_predicate(SessionId, Name, Arity) :-
+    repl_user_predicate(SessionId, Name, Arity),
+    \+ tool_predicate_name(Name).
+
+%% export_clause(+Head, +Body)
+%% Copy + numbervars the clause so variable names are deterministic (A, B, …),
+%% which is required for byte-stable export → reload → export.
+%% export_stats(+SessionId, -Clauses, -Tools, -Scripts)
+export_stats(SessionId, Clauses, Tools, Scripts) :-
+    findall(Name/Arity,
+        (   current_predicate(SessionId:Name/Arity),
+            export_user_predicate(SessionId, Name, Arity)
+        ),
+        Preds0),
+    sort(Preds0, Preds),
+    findall(Count,
+        (   member(PredName/PredArity, Preds),
+            functor(PredHead, PredName, PredArity),
+            aggregate_all(count, clause(SessionId:PredHead, _), Count)
+        ),
+        PredCounts),
+    sum_list(PredCounts, Clauses),
+    findall(Name, session_user_tool_schema(SessionId, Name, _), ToolNames0),
+    sort(ToolNames0, ToolNames),
+    length(ToolNames, Tools),
+    (   current_predicate(SessionId:script_file/2)
+    ->  findall(Path, SessionId:script_file(_, Path), ScriptPaths0),
+        sort(ScriptPaths0, ScriptPaths),
+        length(ScriptPaths, Scripts)
+    ;   Scripts = 0
+    ).
+
+export_clause(Head, Body) :-
+    print_user_clause(Head, Body),
+    nl.
+
+%% format_tool_source(+Head, +Description, +Body, -SourceCode)
+%% Source text for a tool, used by `listing(tools)` and export. Reverses the
+%% load-time task/prompt rewrites so readers see `task/N`, not `task_named/3`.
+format_tool_source(Head, none, Body, SourceCode) :-
+    !,
+    copy_term(Head-Body, NH-NB),
+    numbervars(NH-NB, 0, _),
+    clean_clause_body(NB, CleanBody),
+    (   CleanBody == true
+    ->  format(string(SourceCode), "tool(~q).", [NH])
+    ;   format(string(SourceCode), "tool(~q) :-~n    ~q.", [NH, CleanBody])
+    ).
+format_tool_source(Head, Description, Body, SourceCode) :-
+    copy_term(Head-Description-Body, NH-ND-NB),
+    numbervars(NH-ND-NB, 0, _),
+    clean_clause_body(NB, CleanBody),
+    (   CleanBody == true
+    ->  format(string(SourceCode), "tool(~q, ~q).", [NH, ND])
+    ;   format(string(SourceCode), "tool(~q, ~q) :-~n    ~q.", [NH, ND, CleanBody])
+    ).
+
+%% print_user_clause(+Head, +Body)
+%% Copy + numbervars for deterministic variable names, reverse the load-time
+%% task/prompt rewrites (see clean_clause_body/2), then print in source form.
+print_user_clause(Head, Body) :-
+    copy_term(Head-Body, NumberedHead-NumberedBody),
+    numbervars(NumberedHead-NumberedBody, 0, _),
+    clean_clause_body(NumberedBody, CleanBody),
+    (   CleanBody == true
+    ->  format("~q.~n", [NumberedHead])
+    ;   format("~q :-~n    ~q.~n", [NumberedHead, CleanBody])
+    ).
+
+tool_predicate_name(tool).
+tool_predicate_name(tool_source).
+
+%% repl_script_files(+SessionId, -Paths)
+%% Workspace-relative files linked by script_file/2 facts; the host bundles them.
+repl_script_files(SessionId, Paths) :-
+    (   current_predicate(SessionId:script_file/2)
+    ->  % Only literal paths count; a stray variable path is ignored.
+        findall(Path,
+            (   SessionId:script_file(_, Path),
+                (atom(Path) ; string(Path))
+            ),
+            Paths0),
+        sort(Paths0, Paths)
+    ;   Paths = []
+    ).
+
+%% repl_materialize_embedded(+SessionId)
+%% Writes every embedded_file(Path, Content) fact to its workspace path. Used
+%% after loading a single-file .dml export (where linked scripts are inlined).
+repl_materialize_embedded(SessionId) :-
+    (   current_predicate(SessionId:embedded_file/2)
+    ->  forall(SessionId:embedded_file(Path, Content),
+            (   resolve_workspace_path(Path, Full),
+                catch(
+                    (   file_directory_name(Full, Dir),
+                        make_directory_path(Dir),
+                        setup_call_cleanup(
+                            open(Full, write, Stream),
+                            format(Stream, "~s", [Content]),
+                            close(Stream))
+                    ),
+                    _,
+                    true
+                )
+            ))
+    ;   true
+    ).
+
+%% ============================================================
+%% Prompt Mode (M3)
+%% ============================================================
+
+%% repl_protected_name(+Name)
+%% Reserved names that generated code may not (re)define. repl_delete is a
+%% legitimate harness directive and is allowed through.
+repl_protected_name(Name) :-
+    history_predicate(Name).
+repl_protected_name(Name) :-
+    repl_reserved_name(Name),
+    Name \== repl_delete.
+
+repl_protected_clause((Head :- _)) :-
+    callable(Head),
+    functor(Head, Name, _),
+    repl_protected_name(Name).
+repl_protected_clause(Head) :-
+    callable(Head),
+    functor(Head, Name, _),
+    repl_protected_name(Name).
+
+%% repl_set_meta_catalog(+SessionId, +CatalogText)
+repl_set_meta_catalog(SessionId, CatalogText) :-
+    retractall(session_meta_catalog(SessionId, _)),
+    assertz(session_meta_catalog(SessionId, CatalogText)).
+
+%% repl_prepare_single(+SessionId, +ClauseText, -PreparedTerms)
+%% Reads exactly ONE source term and runs the SAME load-time preprocessing as
+%% parse_dml_string/2: transform_task_calls/3 (task/N, prompt/N ->
+%% task_named/3, prompt_named/3), expand_interpolations/3 ({Var} strings), and
+%% expand_term/2 (e.g. DCG rules). Scratch asserts must be preprocessed exactly
+%% like a file load, or a clause asserted mid-turn keeps task/N, which has no
+%% runtime handler and fails silently.
+%%
+%% Trailing content is an error so `assert` can never silently drop clauses that
+%% `assert_many` would have kept.
+repl_prepare_single(SessionId, ClauseText, PreparedTerms) :-
+    ensure_full_stop(ClauseText, Text1),
+    open_string(Text1, Stream),
+    read_term(Stream, Term, [module(SessionId), variable_names(Bindings)]),
+    (   read_term(Stream, Extra, [module(SessionId)]),
+        Extra \== end_of_file
+    ->  close(Stream),
+        throw(error(syntax_error('assert expects a single clause; use assert_many for multiple'), _))
+    ;   close(Stream)
+    ),
+    preprocess_loaded_term(Term, Bindings, PreparedTerms).
+
+%% repl_read_clause(+SessionId, +ClauseText, -Clause)
+%% Reads exactly one term without preprocessing. Used by retract, which only
+%% needs the predicate's name/arity. Trailing content is an error.
+repl_read_clause(SessionId, ClauseText, Clause) :-
+    ensure_full_stop(ClauseText, Text1),
+    open_string(Text1, Stream),
+    read_term(Stream, Clause, [module(SessionId)]),
+    (   read_term(Stream, Extra, [module(SessionId)]),
+        Extra \== end_of_file
+    ->  close(Stream),
+        throw(error(syntax_error('retract expects a single clause pattern'), _))
+    ;   close(Stream)
+    ).
+
+%% repl_head_of(+Term, -Head)
+%% Strips a rule body, so retracting with a full clause pattern targets the
+%% predicate instead of accidentally matching every rule ((:-)/2).
+repl_head_of((Head :- _Body), Head) :- !.
+repl_head_of(Head, Head).
+
+%% repl_assert_clause(+PreparedTerm, +SessionId)
+%% Asserts one already-preprocessed term, rejecting reserved names.
+repl_assert_clause(PreparedTerm, SessionId) :-
+    (   repl_protected_clause(PreparedTerm)
+    ->  throw(error(permission_error(modify, reserved_name, PreparedTerm),
+                context(repl_assert/3, 'cannot define a reserved predicate')))
+    ;   process_clause(PreparedTerm, SessionId)
+    ).
+
+%% repl_assert(+SessionId, +ClauseText, -Result)
+%% Parses and asserts generated DML with the load-time preprocessing applied,
+%% so scratch-asserted clauses behave exactly like loaded ones.
+%% Refused when frozen; reserved names are rejected.
+repl_assert(SessionId, ClauseText, Result) :-
+    catch(
+        (   guard_not_frozen(SessionId),
+            repl_prepare_single(SessionId, ClauseText, PreparedTerms),
+            forall(member(PreparedTerm, PreparedTerms),
+                repl_assert_clause(PreparedTerm, SessionId)),
+            Result = ok
+        ),
+        AssertError,
+        format(atom(Result), 'error(~w)', [AssertError])
+    ).
+
+%% repl_set_dml_reference(+SessionId, +Text)
+%% Stores the bundled DML reference so the meta prompt can include it.
+repl_set_dml_reference(SessionId, Text) :-
+    retractall(session_dml_reference(SessionId, _)),
+    assertz(session_dml_reference(SessionId, Text)).
+
+%% repl_set_authoring_examples(+SessionId, +Text)
+%% Stores the curated authoring patterns for the meta prompt.
+repl_set_authoring_examples(SessionId, Text) :-
+    retractall(session_authoring_examples(SessionId, _)),
+    assertz(session_authoring_examples(SessionId, Text)).
+
+%% repl_set_meta_template(+SessionId, +Template)
+%% Stores the meta-prompt template (the bundled META_PROMPT.md). Placeholders
+%% {{CATALOG}}, {{REFERENCE}}, {{EXAMPLES}}, {{MANIFEST}}, {{MEMORY}}, {{REQUEST}}
+%% are filled by repl_meta_prompt/3.
+repl_set_meta_template(SessionId, Template) :-
+    retractall(session_meta_template(SessionId, _)),
+    assertz(session_meta_template(SessionId, Template)).
+
+%% repl_set_harness_examples(+SessionId, +Text)
+%% Stores the bundled HARNESS_EXAMPLES.md ({{EXAMPLES}}).
+repl_set_harness_examples(SessionId, Text) :-
+    retractall(session_harness_examples(SessionId, _)),
+    assertz(session_harness_examples(SessionId, Text)).
+
+%% repl_set_prolog_snippets(+SessionId, +Text)
+%% Stores the bundled PROLOG_SNIPPETS.md ({{SNIPPETS}}).
+repl_set_prolog_snippets(SessionId, Text) :-
+    retractall(session_prolog_snippets(SessionId, _)),
+    assertz(session_prolog_snippets(SessionId, Text)).
+
+%% repl_parse_clauses(+SessionId, +ClausesText, -Terms)
+%% Parse and preprocess a block of DML clauses without asserting them.
+repl_parse_clauses(SessionId, ClausesText, Terms) :-
+    ensure_full_stop(ClausesText, Text1),
+    open_string(Text1, Stream),
+    repl_read_prepared_terms(Stream, SessionId, Terms),
+    close(Stream).
+
+repl_read_prepared_terms(Stream, SessionId, Terms) :-
+    read_term(Stream, Term, [module(SessionId), variable_names(Bindings)]),
+    (   Term == end_of_file
+    ->  Terms = []
+    ;   % Apply the same preprocessing as parse_dml_string/2 so scratch clauses
+        % match loaded ones (task/prompt rewrite, interpolation, expand_term).
+        preprocess_loaded_term(Term, Bindings, Prepared),
+        % Directives (e.g. use_module(library(clpfd))) must run while parsing so
+        % their operators are visible to the terms that follow; keep them out of
+        % the returned list so repl_commit_terms does not process them twice.
+        partition_directives(Prepared, Rules, Directives),
+        forall(member(Directive, Directives), process_clause(Directive, SessionId)),
+        append(Rules, Rest, Terms),
+        repl_read_prepared_terms(Stream, SessionId, Rest)
+    ).
+
+partition_directives([], [], []).
+partition_directives([Term|Terms], Rules, Directives) :-
+    (   Term = (:- _)
+    ->  Rules = Rules0,
+        Directives = [Term|Directives0]
+    ;   Rules = [Term|Rules0],
+        Directives = Directives0
+    ),
+    partition_directives(Terms, Rules0, Directives0).
+
+%% repl_commit_terms(+SessionId, +Terms)
+%% Assert already-preprocessed terms (the shared tail of assert_many/define).
+repl_commit_terms(SessionId, Terms) :-
+    forall(member(PreparedTerm, Terms),
+        (   repl_protected_clause(PreparedTerm)
+        ->  throw(error(permission_error(modify, reserved_name, PreparedTerm),
+                    context(repl_assert_many/3, 'cannot define a reserved predicate')))
+        ;   process_clause(PreparedTerm, SessionId)
+        )).
+
+%% repl_assert_many(+SessionId, +ClausesText, -Result)
+%% Parses a block of clauses and asserts them in the order written. Prefer this
+%% for defining a predicate: clause order matters for backtracking, so asserting
+%% one clause at a time can produce a wrong program.
+repl_assert_many(SessionId, ClausesText, Result) :-
+    catch(
+        (   guard_not_frozen(SessionId),
+            repl_parse_clauses(SessionId, ClausesText, Terms),
+            repl_commit_terms(SessionId, Terms),
+            repl_note_touched(SessionId, Terms),
+            Result = ok
+        ),
+        AssertError,
+        format(atom(Result), 'error(~w)', [AssertError])
+    ).
+
+%% repl_term_indicator(+Term, -Name/Arity)
+%% The plain predicate a parsed clause defines. Directives and tool/2 wrappers
+%% have no plain indicator here (process_clause owns them).
+repl_term_indicator((:- _), _) :- !, fail.
+repl_term_indicator((tool(_, _) :- _), _) :- !, fail.
+repl_term_indicator((tool(_) :- _), _) :- !, fail.
+repl_term_indicator(Term, Name/Arity) :-
+    repl_head_of(Term, Head),
+    callable(Head),
+    functor(Head, Name, Arity).
+
+%% repl_note_touched(+SessionId, +Terms)
+%% Record the predicate indicators a term list defines, for history recording.
+repl_note_touched(SessionId, Terms) :-
+    forall(( member(Term, Terms), repl_term_indicator(Term, Name/Arity) ),
+        (   session_edit_touched(SessionId, Name/Arity)
+        ->  true
+        ;   assertz(session_edit_touched(SessionId, Name/Arity))
+        )).
+
+%% repl_edit_touched(+SessionId, -Indicators)
+%% Predicates touched by edit tools since the last clear (sorted, unique).
+repl_edit_touched(SessionId, Indicators) :-
+    findall(Name/Arity, session_edit_touched(SessionId, Name/Arity), Raw),
+    sort(Raw, Indicators).
+
+%% repl_edit_touched_text(+SessionId, -Text)
+%% "Name/Arity, Name/Arity" of the predicates an agent turn touched.
+repl_edit_touched_text(SessionId, Text) :-
+    repl_edit_touched(SessionId, Indicators),
+    with_output_to(string(Text), print_pred_list(Indicators)).
+
+repl_edit_touched_clear(SessionId) :-
+    retractall(session_edit_touched(SessionId, _)).
+
+%% repl_callable_indicator(+Head, -Name, -Arity)
+%% Validate a predicate head: an ordinary (non-operator, non-system) functor.
+repl_callable_indicator(Head, Name, Arity) :-
+    callable(Head),
+    functor(Head, Name, Arity),
+    atom(Name),
+    Name \== '[]',
+    Name \== '{}',
+    \+ repl_system_functor(Name/Arity).
+
+%% Functors that are list/operator/system structure, never user predicates.
+repl_system_functor(Name/_) :-
+    member(Name, ['.', ',', ';', ':-', '->', ':', '|', '!', '\\+', '=', 'is']).
+
+%% repl_retract(+SessionId, +ClausePattern, -Result)
+%% Retracts matching user clauses. Reserved names are protected.
+repl_retract(SessionId, ClauseText, Result) :-
+    catch(
+        (   guard_not_frozen(SessionId),
+            repl_read_clause(SessionId, ClauseText, Pattern),
+            repl_head_of(Pattern, Clause),
+            repl_callable_indicator(Clause, Name, Arity),
+            (   repl_protected_clause(Clause)
+            ->  throw(error(permission_error(modify, reserved_name, Clause),
+                        context(repl_retract/3, 'cannot retract a reserved predicate')))
+            ;   true
+            ),
+            functor(Head, Name, Arity),
+            retractall(SessionId:Head),
+            (   session_user_tools(SessionId, Name)
+            ->  retractall(session_user_tools(SessionId, Name)),
+                retractall(session_user_tool_schema(SessionId, Name, _)),
+                retractall(SessionId:tool_source(Name, _))
+            ;   true
+            ),
+            (   session_edit_touched(SessionId, Name/Arity)
+            ->  true
+            ;   assertz(session_edit_touched(SessionId, Name/Arity))
+            ),
+            Result = ok
+        ),
+        RetractError,
+        format(atom(Result), 'error(~w)', [RetractError])
+    ).
+
+%% repl_delete_predicate(+SessionId, +Name, +Arity, -Result)
+%% Fully remove a predicate. Unlike retract (which only removes matching
+%% clauses and can leave an empty predicate behind), this abolishes it.
+repl_delete_predicate(SessionId, Name, Arity, Result) :-
+    catch(
+        (   guard_not_frozen(SessionId),
+            atom(Name), integer(Arity), Arity >= 0,
+            (   repl_protected_name(Name)
+            ->  throw(error(permission_error(modify, reserved_name, Name/Arity),
+                        context(repl_delete_predicate/4, 'cannot delete a reserved predicate')))
+            ;   true
+            ),
+            catch(abolish(SessionId:Name/Arity), _, true),
+            (   session_user_tools(SessionId, Name)
+            ->  retractall(session_user_tools(SessionId, Name)),
+                retractall(session_user_tool_schema(SessionId, Name, _)),
+                retractall(SessionId:tool_source(Name, _))
+            ;   true
+            ),
+            (   session_edit_touched(SessionId, Name/Arity)
+            ->  true
+            ;   assertz(session_edit_touched(SessionId, Name/Arity))
+            ),
+            Result = ok
+        ),
+        DeleteError,
+        format(atom(Result), 'error(~w)', [DeleteError])
+    ).
+
+%% repl_define(+SessionId, +HeadPatternText, +ClausesText, -Result)
+%% Replace every predicate the clause block defines. It parses the block,
+%% computes its indicators (plus the head pattern's), abolishes each, then
+%% asserts the block. This makes `define` safe no matter how many predicates a
+%% block spans, so a multi-predicate block cannot append duplicate clauses.
+repl_define(SessionId, HeadPatternText, ClausesText, Result) :-
+    catch(
+        (   guard_not_frozen(SessionId),
+            repl_read_clause(SessionId, HeadPatternText, Pattern),
+            repl_head_of(Pattern, HeadClause),
+            repl_callable_indicator(HeadClause, HeadName, HeadArity),
+            repl_parse_clauses(SessionId, ClausesText, Terms),
+            findall(Name/Arity,
+                ( member(Term, Terms), repl_term_indicator(Term, Name/Arity) ),
+                BlockIndicators0),
+            sort([HeadName/HeadArity|BlockIndicators0], Indicators),
+            forall(member(Name/Arity, Indicators),
+                (   repl_protected_name(Name)
+                ->  throw(error(permission_error(modify, reserved_name, Name/Arity),
+                            context(repl_define/4, 'cannot define a reserved predicate')))
+                ;   catch(abolish(SessionId:Name/Arity), _, true),
+                    (   session_user_tools(SessionId, Name)
+                    ->  retractall(session_user_tools(SessionId, Name)),
+                        retractall(session_user_tool_schema(SessionId, Name, _)),
+                        retractall(SessionId:tool_source(Name, _))
+                    ;   true
+                    )
+                )),
+            repl_commit_terms(SessionId, Terms),
+            repl_note_touched(SessionId, Terms),
+            Result = ok
+        ),
+        DefineError,
+        format(atom(Result), 'error(~w)', [DefineError])
+    ).
+
+%% repl_extract_code(+Text, -Source)
+%% Extracts a ```dml fenced block; falls back to the whole answer.
+repl_extract_code(Text, Source) :-
+    atom_string(TextAtom, Text),
+    (   sub_string(TextAtom, Start0, _, _, "```dml")
+    ->  Start is Start0 + 6,
+        % After = 0 takes the remainder of the text (an unbound After would
+        % bind Rest to the empty prefix first).
+        sub_string(TextAtom, Start, _, 0, Rest),
+        % Search for the closing fence by offset: binding Before=0 here would
+        % require the fence to be at the very start of Rest.
+        (   sub_string(Rest, FenceEnd, _, _, "```")
+        ->  sub_string(Rest, 0, FenceEnd, _, Source)
+        ;   Source = Rest
+        )
+    ;   Source = TextAtom
+    ).
+
+%% repl_manifest(+SessionId, -ManifestText)
+%% Compact signatures + tools + entries + directives for the meta prompt.
+repl_manifest(SessionId, Manifest) :-
+    findall(Name/Arity,
+        (   current_predicate(SessionId:Name/Arity),
+            repl_user_predicate(SessionId, Name, Arity)
+        ),
+        Preds0),
+    sort(Preds0, Preds),
+    findall(Name, session_user_tool_schema(SessionId, Name, _), Tools0),
+    sort(Tools0, Tools),
+    findall(Directive, session_directive(SessionId, Directive), Directives0),
+    sort(Directives0, Directives),
+    (   current_predicate(SessionId:module_doc/1),
+        SessionId:module_doc(Summary0)
+    ->  Summary = Summary0
+    ;   Summary = ""
+    ),
+    (   current_predicate(SessionId:doc/2)
+    ->  findall(PI-DocText, SessionId:doc(PI, DocText), Docs0)
+    ;   Docs0 = []
+    ),
+    repl_history_summary(SessionId, HistorySummary),
+    with_output_to(string(Manifest),
+        (   (   Summary == ""
+            ->  format("- skill: (none; add module_doc/1 so the harness describes itself and can be routed)~n")
+            ;   format("- skill: ~w~n", [Summary])
+            ),
+            format("- predicates: ~w~n", [Preds]),
+            format("- tools: ~w~n", [Tools]),
+            format("- directives: ~w~n", [Directives]),
+            (   Docs0 == []
+            ->  format("- docs: (none; add doc(Name/Arity, Text) facts)~n")
+            ;   forall(member(PI-DocText, Docs0), format("- doc(~w): ~w~n", [PI, DocText]))
+            ),
+            format("- history: ~w~n", [HistorySummary])
+        )).
+
+%% repl_meta_memory_text(+SessionId, -Text)
+repl_meta_memory_text(SessionId, Text) :-
+    (   session_meta_memory(SessionId, Memory)
+    ->  true
+    ;   Memory = []
+    ),
+    last_n(Memory, 10, Recent),
+    with_output_to(string(Text),
+        forall(member(message{role: Role, content: Content}, Recent),
+            format("~w: ~w~n", [Role, Content]))).
+
+%% repl_memory_term(+SessionId, +Slot, -TermText)
+%% Serializes a live memory slot (harness|meta) as a Prolog term so a session
+%% can persist it and restore it on `--session` resume.
+repl_memory_term(SessionId, Slot, Text) :-
+    (   Slot == meta
+    ->  (   session_meta_memory(SessionId, Memory)
+        ->  true
+        ;   Memory = []
+        )
+    ;   (   session_repl_memory(SessionId, Memory)
+        ->  true
+        ;   Memory = []
+        )
+    ),
+    with_output_to(string(Text),
+        write_term(Memory, [quoted(true), max_depth(0)])).
+
+last_n(List, N, Tail) :-
+    length(List, Len),
+    (   Len =< N
+    ->  Tail = List
+    ;   Skip is Len - N,
+        length(Prefix, Skip),
+        append(Prefix, Tail, List)
+    ).
+
+%% ============================================================
+%% Harness history (see docs/DML_REPL_SESSION_HISTORY.md)
+%% ============================================================
+
+%% repl_history_load(+SessionId, +Text)
+%% Asserts harness_* history facts (the persisted .deepclause/repl/history.dml)
+%% into the session module so the harness can query prior sessions.
+repl_history_load(SessionId, Text) :-
+    (   var(Text)
+    ->  true
+    ;   open_string(Text, Stream),
+        repl_history_read_stream(Stream, SessionId),
+        close(Stream)
+    ).
+
+repl_history_read_stream(Stream, SessionId) :-
+    catch(read_term(Stream, Term, [module(SessionId)]), _, Term = end_of_file),
+    (   Term == end_of_file
+    ->  true
+    ;   repl_history_assert_term(Term, SessionId),
+        repl_history_read_stream(Stream, SessionId)
+    ).
+
+%% repl_history_record(+SessionId, +FactText)
+%% Asserts one or more history facts into the live module. The recorder persists
+%% the same facts to history.dml; here they become queryable.
+repl_history_record(SessionId, FactText) :-
+    (   var(FactText)
+    ->  true
+    ;   ensure_full_stop(FactText, Text1),
+        open_string(Text1, Stream),
+        repl_history_read_stream(Stream, SessionId),
+        close(Stream)
+    ).
+
+%% Only harness_* facts may be asserted through this path.
+repl_history_assert_term(Term, SessionId) :-
+    (   nonvar(Term),
+        Term \== end_of_file,
+        Term \== none,
+        callable(Term),
+        functor(Term, Name, _),
+        history_predicate(Name)
+    ->  % harness_head is a singleton: keep the latest (rollback moves it back).
+        (   Name == harness_head
+        ->  retractall(SessionId:harness_head(_, _, _, _))
+        ;   true
+        ),
+        % Migrate pre-/5 harness_change facts (they carried an unused Entry arg).
+        (   Term = harness_change(V, Ts, Kind, Sid, Turn, _Entry)
+        ->  assertz(SessionId:harness_change(V, Ts, Kind, Sid, Turn))
+        ;   assertz(SessionId:Term)
+        )
+    ;   true
+    ).
+
+%% repl_rollback(+SessionId, +Source, -Result)
+%% Restores the living module from a history version's serialized source:
+%% abolishes the user predicates and reloads the source (directives, tools and
+%% entries come from the source too). Refused when frozen. Runtime conversation
+%% memory is preserved.
+repl_rollback(SessionId, Source, Result) :-
+    catch(
+        (   guard_not_frozen(SessionId),
+            repl_abolish_user_predicates(SessionId),
+            retractall(session_directive(SessionId, _)),
+            retractall(session_user_tools(SessionId, _)),
+            retractall(session_user_tool_schema(SessionId, _, _)),
+            (   current_predicate(SessionId:tool_source/2)
+            ->  retractall(SessionId:tool_source(_, _))
+            ;   true
+            ),
+            (   Source == ""
+            ->  Result = ok
+            ;   load_code(SessionId, Source, LoadError),
+                (   LoadError == none
+                ->  Result = ok
+                ;   format(atom(Result), 'error(~w)', [LoadError])
+                )
+            )
+        ),
+        RollbackError,
+        format(atom(Result), 'error(~w)', [RollbackError])
+    ).
+
+%% repl_user_predicates(+SessionId, -Preds)
+%% Sorted Name/Arity list of the harness's own predicates.
+repl_user_predicates(SessionId, Preds) :-
+    findall(Name/Arity,
+        (   current_predicate(SessionId:Name/Arity),
+            repl_user_predicate(SessionId, Name, Arity)
+        ),
+        Preds0),
+    sort(Preds0, Preds).
+
+%% repl_user_predicates_text(+SessionId, -Text)
+%% Rendered "name/arity, name/arity" for change diffing on the host side.
+repl_user_predicates_text(SessionId, Text) :-
+    repl_user_predicates(SessionId, Preds),
+    with_output_to(string(Text), print_pred_list(Preds)).
+
+%% repl_predicate_arities(+SessionId, +Name, -Arities)
+%% Sorted arities of a user predicate, e.g. agent_main -> [0,1,2]. Used by
+%% `deepclause run` to pick the agent_main/N to call for the given arguments.
+repl_predicate_arities(SessionId, Name, Arities) :-
+    atom(Name),
+    findall(Arity,
+        (   current_predicate(SessionId:Name/Arity),
+            repl_user_predicate(SessionId, Name, Arity)
+        ),
+        Arities0),
+    sort(Arities0, Arities).
+
+%% repl_history_listing(+SessionId)
+%% Human-readable tail for `listing(history)`.
+repl_history_listing(SessionId) :-
+    (   current_predicate(SessionId:harness_head/4),
+        SessionId:harness_head(Version, Timestamp, HeadSession, _Turn)
+    ->  format("harness_head(~w, ~w, ~w)~n", [Version, Timestamp, HeadSession])
+    ;   format("harness_head(none)~n")
+    ),
+    (   current_predicate(SessionId:harness_session/5)
+    ->  forall(SessionId:harness_session(Sid, Started, Model, Backend, Dir),
+            format("harness_session(~w, ~w, ~w, ~w, ~w)~n", [Sid, Started, Model, Backend, Dir]))
+    ;   true
+    ),
+    (   current_predicate(SessionId:harness_change/5)
+    ->  forall(SessionId:harness_change(V, Ts, Kind, Sid, Turn),
+            format("harness_change(~w, ~w, ~w, ~w, ~w)~n", [V, Ts, Kind, Sid, Turn]))
+    ;   true
+    ).
+
+%% repl_history_summary(+SessionId, -Text)
+%% One-line history for the meta prompt manifest.
+repl_history_summary(SessionId, Text) :-
+    (   current_predicate(SessionId:harness_head/4),
+        SessionId:harness_head(Version, Timestamp, HeadSession, _Turn)
+    ->  true
+    ;   Version = none, Timestamp = none, HeadSession = none
+    ),
+    (   current_predicate(SessionId:harness_session/5)
+    ->  findall(s, SessionId:harness_session(_, _, _, _, _), Sessions0),
+        length(Sessions0, Sessions)
+    ;   Sessions = 0
+    ),
+    (   current_predicate(SessionId:harness_change/5)
+    ->  findall(c, SessionId:harness_change(_, _, _, _, _), Changes0),
+        length(Changes0, Changes)
+    ;   Changes = 0
+    ),
+    format(atom(Text), 'version ~w (updated ~w by ~w), ~w session(s), ~w change(s)',
+        [Version, Timestamp, HeadSession, Sessions, Changes]).
+
+%% repl_meta_prompt(+SessionId, +Request, -PromptText)
+%% Assembles the deterministic code-writing prompt: authoring contract, host
+%% tool catalog, harness manifest, recent meta memory, the request, and the
+%% output contract.
+repl_meta_prompt(SessionId, Request, Prompt) :-
+    (   session_meta_catalog(SessionId, Catalog) -> true ; Catalog = "" ),
+    (   session_dml_reference(SessionId, Reference) -> true ; Reference = "" ),
+    (   session_authoring_examples(SessionId, Authoring) -> true ; Authoring = "" ),
+    (   session_harness_examples(SessionId, Examples) -> true ; Examples = "" ),
+    (   session_prolog_snippets(SessionId, Snippets) -> true ; Snippets = "" ),
+    repl_manifest(SessionId, Manifest),
+    repl_meta_memory_text(SessionId, MemoryText),
+    % The template is the bundled META_PROMPT.md, injected by the host via
+    % repl_set_meta_template/2. The fallback keeps the prompt usable when no
+    % template was set (e.g. a direct repl_meta_prompt/3 call).
+    (   session_meta_template(SessionId, Template)
+    ->  true
+    ;   Template = "You are the DeepClause REPL harness author.~n~nHOST TOOL CATALOG~n{{CATALOG}}~n~nUSER REQUEST~n{{REQUEST}}~n"
+    ),
+    replace_all(Template, "{{CATALOG}}", Catalog, P1),
+    replace_all(P1, "{{REFERENCE}}", Reference, P2),
+    replace_all(P2, "{{AUTHORING}}", Authoring, P3),
+    replace_all(P3, "{{EXAMPLES}}", Examples, P4),
+    replace_all(P4, "{{SNIPPETS}}", Snippets, P5),
+    replace_all(P5, "{{MANIFEST}}", Manifest, P6),
+    replace_all(P6, "{{MEMORY}}", MemoryText, P7),
+    replace_all(P7, "{{REQUEST}}", Request, Prompt).
+
+%% replace_all(+Text, +From, +To, -Out)
+%% Literal, all-occurrences substring replacement. Fills the meta-prompt
+%% template's {{PLACEHOLDER}} sections.
+replace_all(Text, From, To, Out) :-
+    string_codes(Text, TextCodes),
+    string_codes(From, FromCodes),
+    string_codes(To, ToCodes),
+    replace_all_codes(TextCodes, FromCodes, ToCodes, OutCodes),
+    string_codes(Out, OutCodes).
+
+replace_all_codes([], _, _, []) :- !.
+replace_all_codes(Codes, From, To, Out) :-
+    From \== [],
+    (   append(From, Rest, Codes)
+    ->  append(To, Tail, Out),
+        replace_all_codes(Rest, From, To, Tail)
+    ;   Codes = [C|Cs],
+        Out = [C|Tail],
+        replace_all_codes(Cs, From, To, Tail)
+    ).
+
+repl_meta_prompt(Request, Prompt) :-
+    get_session_id(SessionId),
+    repl_meta_prompt(SessionId, Request, Prompt).
+
+%% repl_run_meta(+SessionId, +PromptText, -FrameId, -Error)
+%% Creates the meta frame running the code-writing task.
+repl_run_meta(SessionId, PromptText, FrameId, Error) :-
+    catch(
+        (   repl_initial_state(SessionId, meta, State),
+            create_frame_raw(SessionId, meta, 0,
+                deepclause_mi:repl_meta_solve(PromptText, SessionId, State),
+                FrameId),
+            Error = none
+        ),
+        CreateError,
+        format(atom(Error), '~w', [CreateError])
+    ).
+
+repl_meta_solve(PromptText, SessionId, State) :-
+    nb_setval(current_session_id, SessionId),
+    catch(
+        (   mi_call(
+                task_named(PromptText, [DMLCode, Answer],
+                    [typed_var{name:'DMLCode', type:string},
+                     typed_var{name:'Answer', type:string}]),
+                State, _StateOut),
+            % The task's own memory (incl. the assembled prompt and tool results)
+            % is ephemeral. The host records a clean user/assistant pair with
+            % repl_record_meta/3 after the turn; that becomes the next turn's
+            % conversation history (a normal messages array).
+            engine_yield(meta_result(DMLCode, Answer))
+        ),
+        MetaError,
+        (   format(atom(Msg), '~w', [MetaError]),
+            engine_yield(error(Msg))
+        )
+    ).
+
+%% repl_record_meta(+SessionId, +Request, +Summary)
+%% Appends a short outcome note to meta memory (bounded).
+repl_record_meta(SessionId, Request, Summary) :-
+    (   session_meta_memory(SessionId, Memory)
+    ->  true
+    ;   Memory = []
+    ),
+    append(Memory,
+        [message{role: user, content: Request},
+         message{role: assistant, content: Summary}],
+        Combined),
+    % Keep every system message (compaction checkpoints) and the last 20
+    % conversational messages; naive last_n/3 would evict old checkpoints.
+    findall(M, (member(M, Combined), repl_system_message(M)), SystemMessages),
+    findall(M, (member(M, Combined), \+ repl_system_message(M)), Conversational),
+    last_n(Conversational, 20, Recent),
+    append(SystemMessages, Recent, Bounded),
+    retractall(session_meta_memory(SessionId, _)),
+    assertz(session_meta_memory(SessionId, Bounded)).
+
+%% repl_system_message(+Message)
+repl_system_message(message{role: system, content: _}).
+
+%% repl_get_memory(+SessionId, +Slot, -Messages)
+%% Read a live memory slot as the message list stored in the session.
+repl_get_memory(SessionId, Slot, Messages) :-
+    (   Slot == meta
+    ->  (   session_meta_memory(SessionId, Memory)
+        ->  true
+        ;   Memory = []
+        )
+    ;   (   session_repl_memory(SessionId, Memory)
+        ->  true
+        ;   Memory = []
+        )
+    ),
+    Messages = Memory.
+
+%% repl_set_memory(+SessionId, +Slot, +Messages)
+%% Replace a live memory slot (used by host-side TypeScript compaction).
+repl_set_memory(SessionId, Slot, Messages) :-
+    (   Slot == meta
+    ->  retractall(session_meta_memory(SessionId, _)),
+        assertz(session_meta_memory(SessionId, Messages))
+    ;   retractall(session_repl_memory(SessionId, _)),
+        assertz(session_repl_memory(SessionId, Messages))
+    ).
+
+%% ---- Edit transactions ----
+
+%% repl_snapshot_save(+SessionId)
+%% Snapshots the living module, tool bookkeeping, directives, and harness
+%% memory so a failed prompt leaves the harness untouched.
+repl_snapshot_save(SessionId) :-
+    retractall(repl_snapshot(SessionId, _)),
+    findall(Clause,
+        (   current_predicate(SessionId:Name/Arity),
+            repl_user_predicate(SessionId, Name, Arity),
+            functor(Head, Name, Arity),
+            clause(SessionId:Head, Body),
+            (   Body == true
+            ->  Clause = Head
+            ;   Clause = (Head :- Body)
+            )
+        ),
+        Clauses),
+    findall(Name, session_user_tools(SessionId, Name), Tools),
+    findall(Name-Schema, session_user_tool_schema(SessionId, Name, Schema), Schemas),
+    (   current_predicate(SessionId:tool_source/2)
+    ->  findall(Name-Source, SessionId:tool_source(Name, Source), ToolSources)
+    ;   ToolSources = []
+    ),
+    findall(Directive, session_directive(SessionId, Directive), Directives),
+    (   session_repl_memory(SessionId, Memory) -> true ; Memory = [] ),
+    assertz(repl_snapshot(SessionId, snapshot{
+        clauses: Clauses,
+        tools: Tools,
+        schemas: Schemas,
+        tool_sources: ToolSources,
+        directives: Directives,
+        memory: Memory
+    })).
+
+%% repl_snapshot_restore(+SessionId)
+repl_snapshot_restore(SessionId) :-
+    (   repl_snapshot(SessionId, Snapshot)
+    ->  retract(repl_snapshot(SessionId, Snapshot)),
+        findall(Name/Arity,
+            (   current_predicate(SessionId:Name/Arity),
+                repl_user_predicate(SessionId, Name, Arity)
+            ),
+            Preds),
+        forall(member(AbName/AbArity, Preds),
+            catch(abolish(SessionId:AbName/AbArity), _, true)),
+        forall(member(Clause, Snapshot.clauses), assertz(SessionId:Clause)),
+        retractall(session_user_tools(SessionId, _)),
+        forall(member(Tool, Snapshot.tools), assertz(session_user_tools(SessionId, Tool))),
+        retractall(session_user_tool_schema(SessionId, _, _)),
+        forall(member(SchemaName-Schema, Snapshot.schemas),
+            assertz(session_user_tool_schema(SessionId, SchemaName, Schema))),
+        (   current_predicate(SessionId:tool_source/2)
+        ->  retractall(SessionId:tool_source(_, _))
+        ;   true
+        ),
+        forall(member(SourceName-Source, Snapshot.tool_sources),
+            assertz(SessionId:tool_source(SourceName, Source))),
+        retractall(session_directive(SessionId, _)),
+        forall(member(Directive, Snapshot.directives),
+            assertz(session_directive(SessionId, Directive))),
+        retractall(session_repl_memory(SessionId, _)),
+        assertz(session_repl_memory(SessionId, Snapshot.memory))
+    ;   true
+    ).
+
+%% repl_parse_source(+SessionId, +Source, -Preds, -Error)
+%% Validates generated DML and collects the predicates it defines.
+repl_parse_source(SessionId, Source, Preds, Error) :-
+    catch(
+        (   open_string(Source, Stream),
+            repl_collect_source_predicates(Stream, SessionId, Preds0),
+            close(Stream),
+            (   member(Name0/_, Preds0),
+                repl_protected_name(Name0)
+            ->  format(atom(Error), 'generated code defines reserved predicate ~w', [Name0])
+            ;   sort(Preds0, Preds),
+                Error = none
+            )
+        ),
+        ParseError,
+        format(atom(Error), '~w', [ParseError])
+    ).
+
+%% repl_collect_source_predicates(+Stream, +SessionId, -Preds)
+%% Reads with the session's operator table and executes `:- use_module(...)`
+%% directives as it goes, exactly like the load path. This is what lets library
+%% operators (CLP(FD)'s #=/ins, etc.) be used in committed source: without it,
+%% validation parsed the source with an empty operator table and rejected code
+%% that loads fine.
+repl_collect_source_predicates(Stream, SessionId, Preds) :-
+    read_term(Stream, Term, [module(SessionId)]),
+    (   Term == end_of_file
+    ->  Preds = []
+    ;   (   Term = (:- Directive)
+        ->  catch(process_directive(Directive, SessionId), _, true),
+            Preds = Rest
+        ;   Term = repl_delete(_)
+        ->  Preds = Rest
+        ;   Term = (Head :- _)
+        ->  functor(Head, Name, Arity),
+            Preds = [Name/Arity|Rest]
+        ;   functor(Term, Name, Arity),
+            Preds = [Name/Arity|Rest]
+        ),
+        repl_collect_source_predicates(Stream, SessionId, Rest)
+    ).
+
+%% repl_commit(+SessionId, +Source, -Result)
+%% Transactional commit: validate, replace-by-predicate, then load the returned
+%% source. Result = ok | 'error(Message)'. Never throws; failures are reported
+%% through Result so the caller can decide whether to repair.
+repl_commit(SessionId, Source, Result) :-
+    catch(
+        repl_commit_unsafe(SessionId, Source, Result),
+        CommitError,
+        format(atom(Result), 'error(~w)', [CommitError])
+    ).
+
+repl_commit_unsafe(SessionId, Source, Result) :-
+    guard_not_frozen(SessionId),
+    repl_parse_source(SessionId, Source, Preds, ParseError),
+    repl_commit_from_parse(SessionId, Source, Preds, ParseError, Result).
+
+repl_commit_from_parse(_SessionId, _Source, _Preds, ParseError, Result) :-
+    ParseError \== none,
+    !,
+    commit_error(ParseError, Result).
+repl_commit_from_parse(SessionId, Source, Preds, none, Result) :-
+    forall(member(Name/Arity, Preds),
+        catch(abolish(SessionId:Name/Arity), _, true)),
+    load_code(SessionId, Source, LoadError),
+    (   LoadError == none
+    ->  retractall(session_last_commit(SessionId, _)),
+        assertz(session_last_commit(SessionId, Preds))
+    ;   true
+    ),
+    repl_commit_from_load(LoadError, Result).
+
+%% repl_last_commit_summary(+SessionId, -Text)
+%% Rendered "name/arity, name/arity" of the predicates the last commit replaced.
+repl_last_commit_summary(SessionId, Text) :-
+    (   session_last_commit(SessionId, Preds), Preds \= []
+    ->  with_output_to(string(Text), print_pred_list(Preds))
+    ;   Text = ""
+    ).
+
+print_pred_list([]).
+print_pred_list([Name/Arity]) :-
+    !,
+    format("~w/~w", [Name, Arity]).
+print_pred_list([Name/Arity|Rest]) :-
+    format("~w/~w, ", [Name, Arity]),
+    print_pred_list(Rest).
+
+repl_commit_from_load(LoadError, Result) :-
+    LoadError \== none,
+    !,
+    commit_error(LoadError, Result).
+repl_commit_from_load(none, ok).
+
+commit_error(Message, Result) :-
+    format(atom(Result), 'error(~w)', [Message]).
+
+%% repl_execute_frame(+SessionId, +GoalText, -FrameId, -Error)
+%% Creates a child frame for the meta `execute` tool.
+repl_execute_frame(SessionId, GoalText, FrameId, Error) :-
+    catch(
+        (   read_repl_goal(SessionId, GoalText, Goal, Names),
+            (   repl_reserved(Goal)
+            ->  throw(error(permission_error(execute, reserved_predicate, Goal),
+                        context(repl_execute_frame/4, 'cannot execute a reserved predicate')))
+            ;   true
+            ),
+            repl_initial_state(SessionId, nested, State),
+            create_frame_raw(SessionId, nested, 1,
+                deepclause_mi:repl_solve(Goal, Names, SessionId, State),
+                FrameId),
+            Error = none
+        ),
+        ExecuteError,
+        format(atom(Error), '~w', [ExecuteError])
+    ).
+
 %% determine_agent_goal(+SessionId, +Args, -Goal)
 %% Args is a list of positional arguments - passed directly to agent_main
 %% Prefers arity that matches the number of arguments provided
@@ -529,31 +2450,12 @@ determine_agent_goal(SessionId, Args, Goal) :-
 determine_agent_goal(SessionId, _Args, SessionId:agent_main).
 
 %% step_engine(+SessionId, -Status, -Content, -Payload)
+%% Legacy single-engine entry point: resolves the session's default frame and
+%% delegates to step_frame/4. Kept as a thin wrapper so existing callers are
+%% unaffected by the frame refactor.
 step_engine(SessionId, Status, Content, Payload) :-
-    (   session_engine(SessionId, Engine)
-    ->  catch(
-            (   engine_next(Engine, Result)
-            ->  process_engine_result(Result, Status, Content, Payload)
-            ;   % Engine finished - return trace if enabled
-                Status = finished,
-                Content = '',
-                (   session_trace_enabled(SessionId, true),
-                    session_trace_log(SessionId, TraceLog)
-                ->  Payload = payload{trace: TraceLog}
-                ;   Payload = none
-                )
-            ),
-            Error,
-            (   format(atom(ErrMsg), 'Engine error: ~w', [Error]),
-                Status = error,
-                Content = ErrMsg,
-                (   session_trace_enabled(SessionId, true),
-                    session_trace_log(SessionId, TraceLog)
-                ->  Payload = payload{trace: TraceLog}
-                ;   Payload = none
-                )
-            )
-        )
+    (   session_default_frame(SessionId, FrameId)
+    ->  step_frame(FrameId, Status, Content, Payload)
     ;   Status = error,
         Content = 'No engine found for session',
         Payload = none
@@ -582,6 +2484,13 @@ process_engine_result(request_judgment(Payload), request_judgment, '', Payload)
 %% Tool result from inline tool execution
 process_engine_result(tool_result(Result), tool_result, '',
     payload{result: Result}) :- !.
+%% Goal-mode solution: bindings is a list of Name-RenderedText pairs.
+process_engine_result(solution(Bindings, Deterministic), solution, '',
+    payload{bindings: Bindings, deterministic: Deterministic}) :- !.
+%% Prompt-mode meta task result: generated DML source and an optional direct
+%% answer for simple questions.
+process_engine_result(meta_result(Code, Answer), meta_result, '',
+    payload{code: Code, answer: Answer}) :- !.
 process_engine_result(wait_input(Prompt), wait_input, Prompt, none) :- !.
 process_engine_result(error(Msg), error, Msg, none) :- !.
 process_engine_result(Other, error, Msg, none) :-
@@ -589,15 +2498,23 @@ process_engine_result(Other, error, Msg, none) :-
 
 %% destroy_engine(+SessionId)
 destroy_engine(SessionId) :-
+    % Destroy every frame belonging to this session (the default query frame and
+    % any nested frames still alive). end_frame/1 also clears the default pointer.
+    (   findall(FrameId, session_frame(FrameId, SessionId, _, _), FrameIds)
+    ->  forall(member(FrameId, FrameIds), end_frame(FrameId))
+    ;   true
+    ),
     (   session_engine(SessionId, Engine)
     ->  catch(engine_destroy(Engine), _, true)
     ;   true
     ),
+    retractall(session_default_frame(SessionId, _)),
     retractall(session_engine(SessionId, _)),
     retractall(session_params(SessionId, _)),
     retractall(session_user_tools(SessionId, _)),
     retractall(session_user_tool_schema(SessionId, _, _)),
     retractall(session_pending_input(SessionId, _)),
+    retractall(session_input_cancelled(SessionId)),
     retractall(session_agent_result(SessionId, _)),
     retractall(session_exec_result(SessionId, _)),
     retractall(session_sample_token_result(SessionId, _)),
@@ -671,6 +2588,13 @@ provide_input(SessionId, Input) :-
     assertz(session_pending_input(SessionId, Input)),
     post_signal_to_engine(SessionId, input_provided).
 
+%% provide_input_cancelled(+SessionId)
+%% Non-interactive runs have no human. Signal the waiting input/2 to fail
+%% instead of blocking.
+provide_input_cancelled(SessionId) :-
+    assertz(session_input_cancelled(SessionId)),
+    post_signal_to_engine(SessionId, input_provided).
+
 %% post_signal_to_engine(+SessionId, +Signal)
 %% Posts a signal via dynamic predicate (most reliable for WASM engines)
 %% Falls back to engine_post only if dynamic assert fails
@@ -1697,6 +3621,49 @@ mi_call(get_memory(Messages), StateIn, StateIn) :-
     !,
     get_memory(StateIn, Messages).
 
+%% ============================================================
+%% Media (see docs/DML_MEDIA.md)
+%% ============================================================
+
+%% mi_call(read_media(+Path, -Media), +StateIn, -StateOut)
+%% Binds Media = media(Path, Mime) for a workspace-relative image. The bytes
+%% stay on disk; only the reference enters memory.
+mi_call(read_media(Path, Media), StateIn, StateIn) :-
+    !,
+    get_params(StateIn, Params),
+    interpolate_desc(Path, Params, P),
+    media_mime(P, Mime),
+    Media = media(P, Mime).
+
+%% mi_call(attach_media(+Media), +StateIn, -StateOut)
+%% Appends a user memory message carrying a reference-only media entry, so the
+%% next task/N can see the image.
+mi_call(attach_media(Media), StateIn, StateOut) :-
+    !,
+    media_dict(Media, media{path: Path, mime: Mime}),
+    format(atom(Note), '[attached ~w: ~w]', [Mime, Path]),
+    Message = message{role: user, content: Note, media: [media{path: Path, mime: Mime}]},
+    get_memory(StateIn, Memory),
+    append(Memory, [Message], NewMemory),
+    set_memory(StateIn, NewMemory, StateOut).
+
+%% media_dict(+Media, -Dict)
+%% Accepts media(Path, Mime) or a bare path; normalizes to the storage dict.
+media_dict(media(Path, Mime), media{path: Path, mime: Mime}) :- !.
+media_dict(Path, media{path: Path, mime: Mime}) :- media_mime(Path, Mime).
+
+%% media_mime(+Path, -Mime)
+%% Allowed media types, matching pi image content blocks.
+media_mime(Path, Mime) :-
+    (   string(Path) -> atom_string(Atom, Path) ; Atom = Path ),
+    (   sub_atom(Atom, _, _, 0, '.png')  -> Mime = "image/png"
+    ;   sub_atom(Atom, _, _, 0, '.jpg')  -> Mime = "image/jpeg"
+    ;   sub_atom(Atom, _, _, 0, '.jpeg') -> Mime = "image/jpeg"
+    ;   sub_atom(Atom, _, _, 0, '.gif')  -> Mime = "image/gif"
+    ;   sub_atom(Atom, _, _, 0, '.webp') -> Mime = "image/webp"
+    ;   fail
+    ).
+
 %% ============================================================
 %% Output Predicates
 %% ============================================================
@@ -1729,8 +3696,11 @@ mi_call(input(Prompt, Input), StateIn, StateIn) :-
     engine_yield(wait_input(InterpPrompt)),
     % Use get_next_signal helper which handles both dynamic predicate and engine_fetch
     get_next_signal(SessionId, _Signal),
-    % Retrieve the input provided via provide_input/2
-    (   session_pending_input(SessionId, Input)
+    % A cancelled input request fails the goal (non-interactive policy).
+    (   session_input_cancelled(SessionId)
+    ->  retractall(session_input_cancelled(SessionId)),
+        fail
+    ;   session_pending_input(SessionId, Input)
     ->  retract(session_pending_input(SessionId, Input)),
         add_trace_with_result(SessionId, exit, input, [InterpPrompt], Input, Depth)
     ;   Input = "",  % Default to empty if no input provided
@@ -1752,6 +3722,27 @@ mi_call(log(Text), StateIn, StateIn) :-
     interpolate_desc(Text, Params, InterpText),
     engine_yield(log(InterpText)).
 
+%% mi_call(format(Format, Args), +StateIn, -StateOut)
+%% In REPL mode, capture format/2 output as an output event rather than
+%% writing to the process stdout. Outside the REPL (runDML), keep normal
+%% behavior so existing traces/prompts are unaffected.
+mi_call(format(Format, Args), StateIn, StateIn) :-
+    get_session_id(SessionId),
+    (   session_repl_mode(SessionId, true)
+    ->  with_output_to(string(Text), format(Format, Args)),
+        mi_call(output(Text), StateIn, StateIn)
+    ;   format(Format, Args)
+    ).
+
+%% mi_call(writeln(Value), +StateIn, -StateOut)
+mi_call(writeln(Value), StateIn, StateIn) :-
+    get_session_id(SessionId),
+    (   session_repl_mode(SessionId, true)
+    ->  with_output_to(string(Text), writeln(Value)),
+        mi_call(output(Text), StateIn, StateIn)
+    ;   writeln(Value)
+    ).
+
 %% ============================================================
 %% Context Stack Management - for memory save/restore
 %% ============================================================
@@ -1878,20 +3869,57 @@ mi_call(false, _StateIn, _StateOut) :-
 %% mi_call(retractall(Head), +StateIn, -StateOut)
 %% Database predicates must operate on the session module so DML-side facts
 %% (draft/4, claim/3, ...) are asserted/retracted in the right module.
+%% repl_reserved_clause(+Term)
+%% True when Term defines a reserved predicate. directives and the legitimate
+%% repl_delete harness form are exempt.
+repl_reserved_clause((:- _)) :-
+    !,
+    fail.
+repl_reserved_clause(repl_delete(_)) :-
+    !,
+    fail.
+repl_reserved_clause((tool(ToolHead, _) :- _)) :-
+    !,
+    functor(ToolHead, Name, _),
+    repl_reserved_name(Name).
+repl_reserved_clause((tool(ToolHead) :- _)) :-
+    !,
+    functor(ToolHead, Name, _),
+    repl_reserved_name(Name).
+repl_reserved_clause((Head :- _)) :-
+    functor(Head, Name, _),
+    repl_protected_name(Name).
+repl_reserved_clause(Head) :-
+    functor(Head, Name, _),
+    repl_protected_name(Name).
+
 mi_call(assertz(Head), StateIn, StateIn) :-
     get_session_id(SessionId),
+    guard_not_frozen(SessionId),
+    guard_reserved_clause(Head),
     assertz(SessionId:Head).
 
 mi_call(asserta(Head), StateIn, StateIn) :-
     get_session_id(SessionId),
+    guard_not_frozen(SessionId),
+    guard_reserved_clause(Head),
     asserta(SessionId:Head).
 
+guard_reserved_clause(Head) :-
+    (   repl_reserved_clause(Head)
+    ->  throw(error(permission_error(modify, reserved_name, Head),
+                context(mi_call/3, 'cannot define a reserved predicate')))
+    ;   true
+    ).
+
 mi_call(retract(Head), StateIn, StateIn) :-
     get_session_id(SessionId),
+    guard_not_frozen(SessionId),
     retract(SessionId:Head).
 
 mi_call(retractall(Head), StateIn, StateIn) :-
     get_session_id(SessionId),
+    guard_not_frozen(SessionId),
     retractall(SessionId:Head).
 
 %% ============================================================
@@ -2100,6 +4128,7 @@ resolve_workspace_path(RelPath, FullPath) :-
 mi_call(consult(File), StateIn, StateIn) :-
     !,
     get_session_id(SessionId),
+    guard_not_frozen(SessionId),
     resolve_workspace_path(File, FullPath),
     readutil:read_file_to_string(FullPath, Code, []),
     consult_string(Code, SessionId).
@@ -2146,7 +4175,14 @@ consult_clauses(Stream, SessionId) :-
     ).
 
 %% consult_process_term(+Term, +SessionId)
-%% Process a single term read during consult
+%% Process a single term read during consult. Reserved-name definitions are
+%% refused so consulted files cannot shadow the REPL control surface.
+consult_process_term(Term, _SessionId) :-
+    repl_reserved_clause(Term),
+    !,
+    throw(error(permission_error(modify, reserved_name, Term),
+                context(consult_process_term/2, 'reserved predicate'))).
+
 consult_process_term(:-(Directive), SessionId) :-
     % Handle directives - route through mi_call so custom predicates like consult/1 work
     !,
@@ -2165,7 +4201,7 @@ consult_process_term((tool(ToolHead, Description) :- Body), SessionId) :-
     extract_tool_schema(ToolHead, Description, ToolName, Schema),
     assertz(session_user_tools(SessionId, ToolName)),
     assertz(session_user_tool_schema(SessionId, ToolName, Schema)),
-    format(string(SourceCode), "tool(~w, ~q) :-~n    ~w.", [ToolHead, Description, Body]),
+    format_tool_source(ToolHead, Description, Body, SourceCode),
     assertz(SessionId:tool_source(ToolName, SourceCode)),
     assertz(SessionId:(tool(ToolHead) :- Body)).
 
@@ -2175,7 +4211,7 @@ consult_process_term((tool(ToolHead) :- Body), SessionId) :-
     extract_tool_schema(ToolHead, none, ToolName, Schema),
     assertz(session_user_tools(SessionId, ToolName)),
     assertz(session_user_tool_schema(SessionId, ToolName, Schema)),
-    format(string(SourceCode), "tool(~w) :-~n    ~w.", [ToolHead, Body]),
+    format_tool_source(ToolHead, none, Body, SourceCode),
     assertz(SessionId:tool_source(ToolName, SourceCode)),
     assertz(SessionId:(tool(ToolHead) :- Body)).
 
@@ -2284,6 +4320,22 @@ mi_call(delete_directory(Dir), StateIn, StateIn) :-
     resolve_workspace_path(Dir, FullPath),
     delete_directory(FullPath).
 
+%% mi_call(size_file(File, Size), +StateIn, -StateOut)
+%% size_file/2 is a plain SWI builtin, so it would otherwise resolve `File`
+%% against the WASM process cwd (not the workspace) and demand `/workspace/...`.
+mi_call(size_file(File, Size), StateIn, StateIn) :-
+    !,
+    resolve_workspace_path(File, FullPath),
+    size_file(FullPath, Size).
+
+%% mi_call(time_file(File, Time), +StateIn, -StateOut)
+%% Modifications time (seconds since epoch); same workspace-relative rule as
+%% size_file/2.
+mi_call(time_file(File, Time), StateIn, StateIn) :-
+    !,
+    resolve_workspace_path(File, FullPath),
+    time_file(FullPath, Time).
+
 %% ============================================================
 %% Catch/Throw - STATE THREADED
 %% ============================================================
@@ -2365,6 +4417,8 @@ is_mi_special_predicate(yield(_)).
 is_mi_special_predicate(log(_)).
 is_mi_special_predicate(system(_)).
 is_mi_special_predicate(user(_)).  %% Add user message to context
+is_mi_special_predicate(read_media(_,_)).
+is_mi_special_predicate(attach_media(_)).
 is_mi_special_predicate(task(_)).
 is_mi_special_predicate(task(_,_)).
 is_mi_special_predicate(task(_,_,_)).
@@ -2402,6 +4456,16 @@ is_mi_special_predicate(with_judgment(_,_)).
 is_mi_special_predicate(require_judgment(_,_)).
 %% Context stack management
 is_mi_special_predicate(get_memory(_)).
+is_mi_special_predicate(format(_,_)).
+is_mi_special_predicate(writeln(_)).
+is_mi_special_predicate(input(_,_)).
+is_mi_special_predicate(call(_)).
+is_mi_special_predicate(call(_,_)).
+is_mi_special_predicate(call(_,_,_)).
+is_mi_special_predicate(call(_,_,_,_)).
+is_mi_special_predicate(once(_)).
+is_mi_special_predicate(ignore(_)).
+is_mi_special_predicate(not(_)).
 is_mi_special_predicate(push_context).
 is_mi_special_predicate(push_context(_)).
 is_mi_special_predicate(pop_context).
@@ -2459,6 +4523,8 @@ is_mi_special_predicate(close(_)).
 is_mi_special_predicate(read_string(_,_,_)).
 is_mi_special_predicate(write(_,_)).
 is_mi_special_predicate(exists_file(_)).
+is_mi_special_predicate(size_file(_,_)).
+is_mi_special_predicate(time_file(_,_)).
 is_mi_special_predicate(exists_directory(_)).
 is_mi_special_predicate(directory_files(_,_)).
 is_mi_special_predicate(make_directory(_)).
@@ -2472,6 +4538,105 @@ is_mi_special_predicate(use_module(_,_)).
 is_mi_special_predicate([_]).
 is_mi_special_predicate([_|_]).
 
+%% mi_call(call(Goal), +StateIn, -StateOut)
+%% Route call/1 through the meta-interpreter so backtracking and the
+%% reserved-predicate guard apply (a bare call/repl_* would bypass them).
+mi_call(call(Goal), StateIn, StateOut) :-
+    guard_reserved_goal(Goal, StateIn),
+    !,
+    mi_call(Goal, StateIn, StateOut).
+
+%% mi_call(call(Closure, Extra...), +StateIn, -StateOut)
+%% call/2..4 must also route through the meta-interpreter; otherwise a wrapped
+%% task/prompt/exec runs in raw Prolog, where task_named/3 does not exist.
+mi_call(call(Goal, A), StateIn, StateOut) :-
+    !,
+    extend_callable(Goal, [A], Callable),
+    mi_call(call(Callable), StateIn, StateOut).
+
+mi_call(call(Goal, A, B), StateIn, StateOut) :-
+    !,
+    extend_callable(Goal, [A, B], Callable),
+    mi_call(call(Callable), StateIn, StateOut).
+
+mi_call(call(Goal, A, B, C), StateIn, StateOut) :-
+    !,
+    extend_callable(Goal, [A, B, C], Callable),
+    mi_call(call(Callable), StateIn, StateOut).
+
+%% extend_callable(+Closure, +ExtraArgs, -Callable)
+extend_callable(Closure, Extra, Callable) :-
+    Closure =.. List,
+    append(List, Extra, Extended),
+    Callable =.. Extended.
+
+%% mi_call(once(Goal), +StateIn, -StateOut)
+%% once/1 must route through the meta-interpreter. As a plain builtin it would
+%% run Goal in raw Prolog, so a wrapped task/prompt/exec fails with
+%% task_named/3 undefined. Commits to the first solution of Goal, like once/1.
+mi_call(once(Goal), StateIn, StateOut) :-
+    !,
+    once(mi_call(Goal, StateIn, StateOut)).
+
+%% mi_call(ignore(Goal), +StateIn, -StateOut)
+mi_call(ignore(Goal), StateIn, StateOut) :-
+    !,
+    (   once(mi_call(Goal, StateIn, StateOut0))
+    ->  StateOut = StateOut0
+    ;   StateOut = StateIn
+    ).
+
+%% mi_call(not(Goal), +StateIn, -StateOut)  (alias for \+/1)
+mi_call(not(Goal), StateIn, StateIn) :-
+    !,
+    mi_call(\+(Goal), StateIn, StateIn).
+
+%% Refuse reserved predicates invoked directly in non-meta frames. This is the
+%% second of the three-place reserved guard (execute, mi_call, assert/load).
+mi_call(Goal, StateIn, _StateOut) :-
+    guard_reserved_direct(Goal, StateIn),
+    !,
+    throw(error(permission_error(execute, reserved_predicate, Goal),
+                context(mi_call/3, 'cannot invoke a reserved REPL predicate'))).
+
+%% guard_reserved_goal(+Goal, +StateIn)
+%% Throws when Goal names a reserved predicate and the frame is not meta.
+guard_reserved_goal(Goal, StateIn) :-
+    (   is_dict(StateIn), get_dict(frame_kind, StateIn, meta)
+    ->  true
+    ;   nonvar(Goal),
+        callable(Goal),
+        functor(Goal, Name, _),
+        repl_reserved_name(Name)
+    ->  throw(error(permission_error(execute, reserved_predicate, Name),
+                context(mi_call/3, 'cannot invoke a reserved REPL predicate')))
+    ;   true
+    ).
+
+guard_reserved_direct(Goal, StateIn) :-
+    (   is_dict(StateIn), get_dict(frame_kind, StateIn, meta)
+    ->  fail
+    ;   nonvar(Goal),
+        callable(Goal),
+        functor(Goal, Name, _),
+        repl_reserved_name(Name)
+    ).
+
+%% Untransformed task/N and prompt/N (N >= 2) are source-level sugar rewritten
+%% to task_named/3 / prompt_named/3 by transform_task_calls/3 at load time.
+%% There is no runtime handler for the untransformed form, so it would match no
+%% clause and fail silently (looking like an inexplicable "0 solutions"). Fail
+%% loudly instead: reaching here means a clause was asserted/run without the
+%% load-time preprocessing (assert/assert_many now apply it, so this is a guard).
+mi_call(Goal, _StateIn, _StateOut) :-
+    compound(Goal),
+    functor(Goal, Name, Arity),
+    Arity >= 2,
+    ( Name == task ; Name == prompt ),
+    !,
+    throw(error(domain_error(unrewritten_task_form, Goal),
+                context(mi_call/3, 'task/N and prompt/N are rewritten at load time (task_named/3, prompt_named/3); preprocess the clause before running it'))).
+
 %% mi_call(Goal, +StateIn, -StateOut)
 %% Catch-all for built-in and user-defined predicates
 %% MUST NOT match special predicates that have dedicated handlers
@@ -2689,6 +4854,17 @@ expand_body_interp(Goal, Bindings, ExpandedGoal) :-
         rebuild_goal(Functor, StringArg, ExpandedRestArgs, ExpandedGoal)
     ).
 
+% Goals whose interpolated string is NOT the first argument (verify/3, judge/2,
+% choose/4, rate/4, probability/3, holds/2,3, and any user predicate): hoist the
+% interpolation into a preceding goal.
+expand_body_interp(Goal, Bindings, ExpandedGoal) :-
+    compound(Goal),
+    Goal =.. [Functor|Args],
+    expand_args_hoist(Args, Bindings, PreGoals, ExpandedArgs, true),
+    !,
+    Bare =.. [Functor|ExpandedArgs],
+    prepend_goals(PreGoals, Bare, ExpandedGoal).
+
 % Other goals - expand arguments
 expand_body_interp(Goal, Bindings, ExpandedGoal) :-
     compound(Goal), !,
@@ -2753,6 +4929,34 @@ expand_rest_args([A|As], Bindings, [EA|EAs]) :-
     expand_body_interp(A, Bindings, EA),
     expand_rest_args(As, Bindings, EAs).
 
+%% expand_args_hoist(+Args, +Bindings, -PreGoals, -Args2, -Hoisted)
+%% Expand each argument; any interpolated string becomes a goal in PreGoals and
+%% its argument becomes the temp variable that goal binds.
+expand_args_hoist([], _, [], [], false).
+expand_args_hoist([Arg|Args], Bindings, PreGoals, [Expanded|EArgs], Hoisted) :-
+    expand_arg_hoist(Arg, Bindings, Pre, Expanded, ThisHoisted),
+    expand_args_hoist(Args, Bindings, Rest, EArgs, RestHoisted),
+    append(Pre, Rest, PreGoals),
+    (   ThisHoisted == true
+    ->  Hoisted = true
+    ;   Hoisted = RestHoisted
+    ).
+
+expand_arg_hoist(Arg, Bindings, [FormatGoal], TempVar, true) :-
+    (   string(Arg)
+    ;   atom(Arg)
+    ),
+    string_needs_interpolation(Arg),
+    !,
+    build_format_call(Arg, Bindings, TempVar, FormatGoal).
+expand_arg_hoist(Arg, _, [], Arg, false).
+
+%% prepend_goals(+PreGoals, +Goal, -Expanded)
+prepend_goals([], Goal, Goal) :- !.
+prepend_goals(Goals, Goal, Expanded) :-
+    list_to_conjunction(Goals, Conj),
+    Expanded = (Conj, Goal).
+
 %% flatten_conjunction(+A, +B, -Conj)
 %% Flatten nested conjunctions properly
 flatten_conjunction((A1, A2), B, Result) :- !,